The guide to UDO Release 6 Patchlevel 0 January 3rd 1997 by Dirk Hagedorn Asmecke 1 59846 Sundern Germany Internet: DirkHage@aol.com MausNet: Dirk Hagedorn @ MK2 ====================================================================== Contents ====================================================================== 1 Introduction 1.1 Preface 1.2 What UDO can('t) do for you 1.3 Do you need UDO? 1.4 Once upon a time 1.5 Contact addresses 1.6 Thanks 2 Legal information 2.1 Copyright 2.2 Disclaimer 2.3 Trademarks 3 Money, money, money 3.1 Shareware 3.2 How much does UDO cost? 3.3 How much do upgrades cost? 3.4 Registration 3.5 Registration in Great Britain 4 Installation 4.1 Installing the Atari version 4.2 Installing the DOS version 4.3 Installing the Macintosh version 4.4 Installing the Unix versions 5 Usage 5.1 Command line version 5.2 GEM version 5.3 Macintosh version 5.4 UDO Shell for Windows 6 The syntax of UDO 6.1 A short example 6.2 Basics 6.3 Structuring 6.4 Emphasising text 6.5 Special characters 6.6 Syllabification 6.7 Images 6.8 Hypertext commands 6.9 Miscellaneous 7 Tips & tricks 7.1 Seven rules for writing UDO source files 7.2 General tips & tricks 7.3 Tips & tricks according to LaTeX 7.4 Tips & tricks according to ST-Guide 7.5 Tips & tricks concerning Windows Help Appendix ======== A Frequently asked questions A.1 General questions A.2 Questions concerning ASCII A.3 Questions concerning HTML A.4 Questions concerning manpages A.5 Questions concerning LaTeX A.6 Questions concerning Linuxdoc-SGML A.7 Questions concerning Pure C Help A.8 Questions concerning the Rich Text Format A.9 Questions concerning ST-Guide A.10 Questions concerning Texinfo A.11 Questions concerning Turbo Vision Help A.12 Questions concerning Windows Help B Bugs C Error messages D This & that D.1 Facts, facts, facts D.2 Programming environment D.3 Generated files E History E.1 Last minute changes E.2 Release 6 E.3 Release 5 E.4 Release 4 E.5 Release 3 F Command index F.1 A... F.2 B... F.3 C... F.4 D... F.5 E... F.6 F... F.7 G... F.8 H... F.9 I... F.10 L... F.11 M... F.12 N... F.13 O... F.14 P... F.15 R... F.16 S... F.17 T... F.18 U... F.19 V... F.20 W... F.21 X... F.22 *... ====================================================================== Chapter 1 Introduction ====================================================================== 1.1 Preface ============ Welcome to UDO! You are reading the revised documentation of the revised program called UDO written by a quite overworked author that still is hoping that anybody outside there understands his quite unrevised knowledge of writing English documentations. UDO is a powerful and multipurpose utility for making a documentation or any other text file that is needed in one text format or more. Though UDO is powerful it's quite easy to understand and to use. If you take a look at the size of this documentation you will notice immediately that UDO has to be quite powerful. Many users get deterred of the size of this documentation and try to use UDO without having read it. Unfortunately, exactly these people will ask lots of questions later on without knowing that their questions could be answered by simply reading this documentation. Due to this fact I want to note at the beginning of this documentation that you will only be able to use UDO in an efficient way if you read the complete documentation one time at least and if you experiment with the added examples. Please take some time, sit down, take a cup of tea or coffee and read this documentation from the beginning to the end. You don't have to learn everything by heart but you should be able to find things quickly if there will be questions later on. If you will detect parts where things are described in a too short, wrong or misleading way: please let me know! UDO is "my little child" and it wouldn't be the first time that an author has forgotten to describe some important parts. And if you have any problems with my English: please let me know, too! I did what I can but you without any doubts you will find some awful parts. Please note that UDO is Shareware. I have been spending a lot of my spare time for this project. If you want to use UDO please register for it. I hope that UDO will become an unrenounceable utility for you and you will have more time for the really important things. Dirk Hagedorn Sundern, December 10th 1996 1.2 What UDO can('t) do for you ================================ UDO has been originally developed to make it easier for you to write software documentations or other kinds of text files that have to be available in more than one format. UDO can be a great help if you want to make a single destination format, too. A beginner will have less problems when learning the UDO syntax instead of learning LaTeX or HTML. So if you want to make LaTeX or HTML files it should be easier to get to know how to make them using UDO instead of writing them on your own. When writing LaTeX or HTML files you have to keep attention not to use any of their special command characters. In comparison to that UDO will convert these special characters for you when converting the source file to LaTeX or HTML. But this is not the only thing UDO can do for you. UDO is a multilingual program. You can make German, English, French, Italian and Swedish texts. UDO knows how "Table of contents", "Appendix", "Figure" or "Table" is called in the other countries. The date is also printed out in the right way depended of the selected language. The syntax of UDO is easy to learn. To make some small documentations you just have to learn about ten to fifteen commands; as many as you have to learn when you try to learn LaTeX or HTML. When you have written an UDO source file you can convert it into the following formats: 1. Apple QuickView 2. ASCII 3. HTML (Hypertext Markup Language) 4. LaTeX 2.09, LaTeX2e 5. Linuxdoc-SGML 6. LyX 7. Manualpage 8. NROFF 9. Pure C Help 10. RTF (Rich Text Format) 11. Source code (C and Pascal) 12. ST-Guide 13. Texinfo 14. Turbo Vision Help 15. Windows Help As you can see some formats are just interesting for specific operating systems, but you can also see that the list contains come formats that can be used on nearly any existing operating system. In most cases UDO doesn't make files that are ready to use because have to run a further software to view, print or convert the document. E.g. you have to convert the Windows Help source file (saved by UDO) with the Microsoft Help Compiler HC.EXE into a Windows Help file. Or you have to import the RTF file into a text processor to print it. UDO tries to help the author of a documentation as much as possible. Next to the conversion into the destination format UDO offers you the following features: ü automatically generated title pages, tables of contents, head lines and bottom lines, ü chapter numbering, ü tables, ü automatically generated hypertext links, ü support for different text styles, ü automatic conversion of umlauts and other special characters, ü a large variety of layout commands for making lists, enumera- tions, descriptions, justified text, centred or indented text or text with a right alignment, ü image support, ü automatic line breaks with a half-automatic syllabification. UDO is not the perfect program for all purposes. The conversion into ASCII, ST-Guide, HTML, LaTeX and Windows Help is nearly perfect. Some formats (like Linuxdoc-SGML and LyX) are quite young and haven't been tested enough. You will surely find some aspects that have to be changed in the near future. There are some points that UDO can't manage yet but will be implemen- ted in the very near future: a automatically generated index, list of figures and list of tables. Just wait some months and you will get UDO Release 7 with all these features. To make complex files like newspapers that is impossible with UDO because it can't wrap text around images and it can't generated files with two or more text columns. In addition to that UDO hasn't got an implemented automatic syllabification. UDO is just a "one way" converter. UDO can't convert LaTeX, HTML or RTF to the UDO format. It is only able to convert the UDO format into LaTeX etc. Maybe there will be a HTML2UDO or SGML2UDO converter in the near future. To sum it up it can be said that UDO can't manage the following things and won't be able to manage them in the future: 1. UDO can only convert its format into the upper standing formats. UDO can't convert them into its own format. Maybe there will be some other converters in the near future. 2. UDO can't make binary formats (like WinWord documents). It can only make make formats that are based on ASCII. 3. UDO doesn't support an automatic syllabification. You have to tell UDO explicitely where it is allowed to split up words. I don't want to implement an automatic syllabification because there are only some formats that would profit from it. 4. UDO can't wrap text around images. UDO can't save multi-columned texts, too. These functions are part of desktop publishing and not of a software like UDO. 1.3 Do you need UDO? ===================== If you can answer one or more of the following question with "Yes" UDO should be worth to take a look at. If can't answer any question with "Yes" it's quite possible that you don't need UDO and that you can stop reading this manual right here. ü Have you written a text with a general contents and do you want to let some people, that don't run the same operating system, read it? ü Are you a programmer and do you want to distribute your software with an ASCII manual and an online manual for Windows, Turbo Vision, GNU Info or ST-Guide? ü Are you a programmer and do you want to print out the manual with LaTeX or a text processor that can import the Rich Text Format? ü Do you only need an ASCII manual but you always get rid of checking the line breaks, chapter numbers and the table of contents? ü Do you want to publish a hypertext inside the World Wide Web but you don't own a powerful HTML editor that can enter links, convert special characters or split up the document into different files automatically? ü Do you want to make an online manual for a Windows software but you don't want to pay a lot of money for a software that costs more than 20 times the price of UDO but can do only a little bit more? ü Are you the author of a Pure C library for the Atari computers and you need a descriptions of the library routines for Pure C Help and ST-Guide? Did you answer any question with "Yes"? Fine! You didn't? Then read the questions once more. ;-) 1.4 Once upon a time ===================== It was autumn 1994 when I wrote some little programs for which I needed an ASCII manual, an online help and a printed documentation. In all cases I began writing the ASCII manual. In a copy of it I inserted hypertext commands. Finally the ASCII manual was imported into a text processor, layouted and printed. It didn't take a long time for me to recognize that this was an inefficient work: if there were any changes in one of the files both the others had to be changed in the same way. And if there were lots of changes it was necessary to start the whole procedure right from the beginning. When I finished these manuals I said to myself: "Oh no, Dirk, there must be another and easier way to get different versions of one text file!". January 1995 I started to think about a new text format with the project name "UDO" (as the abbreviation for Universal DOcument). The UDO syntax should be easy to learn and flexible enough and so I decided to create a syntax like LaTeX. Next to this I began writing the software that was able to convert this new text format into ASCII, ST-Guide and LaTeX: UDO was born! At this time UDO was really a small program with only some features. The syntax contained about 10 commands and the source code was about 10 KB large. Nevertheless this small hack was of a great help for myself and the upper described horror scenario was history. Since this time UDO has been growing up day by day. UDO now supports many different text formats, it offers a large variety of layouting commands, it's available for different operating system and the size of its source code and documentation is now a hundred times larger than it was in former days. In these two years UDO has become to an operating system independent, very powerful and - proverbially said - universal tool. 1.5 Contact addresses ====================== If you want to register UDO, if you want have questions, if you want to make any suggestions or if you want to report bugs please use one of the following addresses. If possible contact me via email. Address: Dirk Hagedorn Asmecke 1 59846 Sundern Germany Telephone/Fax: +49 2933 77979 MausNet: Dirk Hagedorn @ MK2 (no mails > 16 KB) Internet: DirkHage@aol.com World Wide Web: http://members.aol.com/DirkHage/www/index.htm 1.6 Thanks =========== At this point I want to say "Thank you" to the following people because of their effective help. Without this help UDO wouldn't be like it is today. Thank you Denesh Bhabuta for supporting UDO in Great Britain Alexander Clauss for compiling the HP-UX 300/400 version Dirk Haun, one of the fathers of UDO Patrick Jerchel for managing the mailing list Peter Klasen, the first registered user of UDO Martin Loos for managing the old mailing list Martin Osieka for porting UDO to MacOS Rainer Riedl for compiling the BeOS version Tom Thomasson for supporting UDO in Sweden In addition to that I want to thank all users of UDO for their indefatigable efforts to make UDO better and better. ====================================================================== Chapter 2 Legal information ====================================================================== 2.1 Copyright ============== UDO and its documentation are copyrighted by Dirk Hagedorn, Sundern, Germany. UDO is distributed as shareware and may be copied to third persons in a noncommercial way if all the following requirements are met: ü You have to copy the software with all and unchanged files. ü You have to copy the software free of charge. Uploading UDO to a noncommercial BBS or FTP server is allowed. ü You aren't allowed to add files to the archives e.g. advertise- ments for a BBS or for Public Domain series. You aren't allowed to rename the archives or to to compress them with another archiver. ü If you want to distribute UDO via Public Domain floppy discs you may do this only if the price of a single floppy disc is lower than 5 Pounds Sterling, 6 $US and 10 DM (or the same value in another currency). ü If you want to distribute UDO via CD-ROM you may do this only, if I, Dirk Hagedorn, will get a copy of this CD-ROM free of charge and the if the CD-ROM will be published before December 31st 1997. I want to avoid that old versions of UDO are still copied even if there are out of date. If you read this text 1998 or later please contact me to get to know if there's a younger version existing! 2.2 Disclaimer =============== Though UDO has been developed thoroughly and has been tested for a long period of time there is no warranty for the program or the contents of this documentation. UDO is provided "as is" without warranty of any kind, including but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk is with you. Should UDO prove defective you assume the cost of all necessary servicing, repair or correction. Nevertheless the author will be glad if you send him bug reports. 2.3 Trademarks =============== This documentation uses names of products and companies that may be trademarks or registered trademarks. You may not conclude that these names are free of use even if they are not marked explicitly. Atari, TOS and MultiTOS are trademarks or registered trademarks of Atari Corporation. Arial and Times New Roman are registered trademarks of Monotype Corporation PLC. GEM and GEM Desktop are trademarks or registered trademarks of Digital Research. Mac, Macintosh and MacOS are registered trademarks of Apple Computer Inc. MS-DOS, Windows, Windows 95 and Windows NT are registered trademarks of Microsoft Corporation. Unix is a registered trademark of X/Open Company Ltd. ====================================================================== Chapter 3 Money, money, money ====================================================================== 3.1 Shareware ============== UDO is distributed as shareware. This means: ü You are allowed to check for exactly four weeks if UDO meets your requirements! ü It's forbidden to publish any text you have made with UDO during this trial period. ü After the trial period of four weeks you have to decide whether you want to buy UDO (see "Registration") or if you don't want to use it. If you don't want to buy UDO you are obligated to delete UDO and all its additional files from your hard disc. If you don't you will work with a black copy of UDO! If I will get less registrations than I expect I... 1. ...will increase the number of limitations (e.g. limited document sizes, exchanged characters in the destination file or ugly speed limitations), or I... 2. ...won't publish further versions of UDO and give them only to registered users, or I... 3. ...will stop going on developing UDO. That's no joke! In the past I was often disappointed due to the amount of registrations I got for other software of mine. Please believe me that I cannot laugh anymore about users that are too lazy to pay for shareware. In former versions UDO didn't have any limitations. But due to the unsatisfying resonance from Unix and DOS users I implemented limitations in all UDO versions: 1. UDO will print an ugly message at the end of every page. 2. The switch !use_about_udo is set automatically for all destina- tion formats. When you have paid the shareware fee you will get a personalised keycode. With this keycode you will be able to disable these limitations. 3.2 How much does UDO cost? ============================ You can believe me that I have thought very long about the price of UDO. So please read this section until the end. I don't want to tell you the price I would have to demand because it is higher than an averaged user wants to pay for shareware nowadays. But I think that the current price of UDO is a good compromise between "dream and reality". I hope that it's fair enough for you and UDO is worth paying this amount of money. The height of the shareware fee depends on your status, whether you want to use UDO for private, commercial or educational purposes: The price for private users =========================== The shareware fee for a systemwide licence of UDO for private users is 50 DM (35 $US, 25 Pounds Sterling, 40 SFR, 350 ÚS, 55 NFL, 150 FF). You are a private user if you make documentations or other texts for products that cost less than 100 DM (70 $US, 50 Pounds Sterling, 80 SFR, 700 ÚS, 110 NFL, 34 FF). Thus all authors that are programming only freeware, public domain or shareware that cost less than 100 DM are private users. Private users have to pay the shareware only once. After the registration private users are allowed to use UDO simultaneously on any operating system UDO is available for. If you recognize that you are a commercial user after having paid the shareware fee for private users you are forced to pay the difference! The price for commercial users ============================== The shareware fee for a single licence of UDO for commercial users is 150 DM (100 $US, 75 Pounds Sterling, 120 SFR, 1050 ÚS, 165 NFL, 450 FF). "Single licence" means that UDO may only be installed on one computer that isn't connected to any kind of network. If you want to use UDO on several computers or in a network you have to buy additional licences for any additional working places. Additional licences costs 50 DM each (35 $US, 25 Pounds Sterling, 40 SFR, 350 ÚS, 55 NFL, 150 FF). You have to guarantee that the maximum number of users of UDO cannot be higher than the amount of licences you have bought. If you need 20 or more licences you can ask me for a special price for your specific needs. A commercial user is who uses UDO for writing documentations or other texts for one or more products that cost more than 100 DM (70 $US, 50 Pounds Sterling, 80 SFR, 700 ÚS, 110 NFL, 34 FF). Companies, enterprises and other commercial oriented institutions that use UDO for internal purposes are commercial users, too. The price for schools and universities ====================================== I offer special prices for schools, universities and other educational institutions. Please ask me for the price for the amount of needed licences. Please note: 1. All prices are inclusive value-added tax. 2. After having paid the shareware fee you will receive an invoice and a personalized keycode. With this keycode you will be able to disable the limitations of the shareware version. 3. If you think (like myself) that UDO is worth more than the upper shown prices, don't hesitate to pay more. A last request... ================= Dear private users, if you want to use UDO without any twinges at your working place, please try to convince your boss or any other superior to buy one ore more licences of UDO. The low price of UDO can be afforded by really every company and can be completely depreciated. Every additional income can help me to cover my costs payments for books, compilers and telephone/modem calls. And you can believe me that these costs aren't low due to the size of this project. 3.3 How much do upgrades cost? =============================== You have to pay an upgrade fee for upgrading an old release to the current one. The height of this upgrade fee depends on which release you have currently registered and if you are a private, commercial or "educational" user. The following table shows the upgrade fees in Deutsche Mark. The second table shows you the equivalent values in your currency. from to | Private | Commercial | Education --------------------------+---------+------------+----------- Release 3 Release 6 | 15 DM | 50/10 DM | -- Release 4 Release 6 | 10 DM | 30/10 DM | -- Rel. 5 (1996) Release 6 | 0 DM | 0 DM | 0 DM Rel. 5 (1997) Release 6 | 10 DM | 50/10 DM | 50/10 DM DM | $US | Pounds | sFR | ÎS | nFL FF ----+-----+--------+-----+-----+---------- 10 | 7 | 5 | 13 | 70 | 11 30 15 | 10 | 8 | 20 | 105 | 17 45 30 | 20 | 15 | 40 | 210 | 34 60 50 | 35 | 25 | 65 | 350 | 56 150 If you have registered UDO Release 5 in 1996 you don't have to pay any upgrade fee. The new keycodes will be sent to you on demand (email preferred). If you have registered UDO Release 5 in 1997 or later you will have to pay the upgrade fees listed in the table in the row labelled "Rel. 5 (1997)". The values in the columns for commercial and educational users are the upgrade fees for the first licence (left value) and additional licences (right value). 3.4 Registration ================= The height of the shareware or upgrade fee depends on your status. How much money you have to pay you will find in "How much does UDO cost?" and "How much do upgrades cost?". Users from Great Britain are recommended to register UDO via Denesh Bhabuta. Users from Sweden are recommended to register UDO via Tom Thomasson. The appropriate amount of money can be paid by sending a cheque, a Eurocheque or cash or by transferring the amount of money to my bank account. If you really want to risk to send cash please send Deutsche Mark and insert a black piece of paper into the envelope so nobody can look inside gets the idea to steal the letter. Please send cheques, Eurocheques or cash to: Dirk Hagedorn Asmecke 1 59846 Sundern Deutschland If you prefer transferring the money to my bank account use these data: Account holder: Dirk Hagedorn Account number: 3 561 164 Bank: Sparkasse Arnsberg-Sundern, Germany Bank code: 466 500 05 In all cases please don't forget to send me ü your name ü your complete address ü your email address (if available) ü on which operating system(s) you want to use UDO After having received the money I will send you a bill and a personalized keycode. With the keycode you can disable the limitations of the shareware version. Services for registered users ----------------------------- New releases of UDO are released two or three times per year at maximum. Registered users are enabled to use current beta versions at any time. Because UDO is available for many operating systems and I don't have so much time to compile new release every time I change some things, new releases will be published only if the number of changes is high enough. For registered users after about two weeks updated versions are published. In these version old bugs are fixed, new destination formats are presented and wishes of registered users are considered if they may be realised. Registered users can download these updates via modem or FTP or they can order them by sending a formated floppy disk with a readdressed envelope and 2 DM for stamps. It goes without saying that registered users will get gratis support via via (e)mail. Questions of registered users will be answered as detailed as possible. 3.5 Registration in Great Britain ================================== It's recommended that British users register UDO via Denesh Bhabuta. Users from outside Great Britain should register UDO directly via Dirk Hagedorn. The shareware fee depends on your status. How much money you have to pay you will find in "How much does UDO cost?" or "How much do upgrades cost?". To register UDO via Denesh Bhabuta please send a cheque or postal order for the appropriate amount made payable to "Denesh Bhabuta". Denesh also accepts Eurocheques and International Money Orders made payable to him. Send this along with your full address, e-mail address and a short note which version of UDO on which operating system you are using to Address: Denesh Bhabuta CyberSTrider 203 Parr Lane Bury BL9 8JW E-Mail: dbhabuta@cix.compulink.co.uk danny@micros.hensa.ac.uk dbhabuta@mag-net.co.uk When you register, you are entitled to ü Master Disk with latest version(s) of UDO ü Keycode to register this versions of UDO ü E-mail, snail-mail and telephone support ü Free update service (as long as the fee doesn't rise or it becomes commercial) Your keycode will initially be sent by e-mail if possible. Users who register via Denesh are entitled to this service. To receive free updates, please send a blank unlabelled floppy disk with a stamped self addressed envelope to the above address. ====================================================================== Chapter 4 Installation ====================================================================== 4.1 Installing the Atari version ================================= To install UDO onto an Atari or onto a computer with a compatible operating system (e.g. MagiCMac, MagiC-PC, GEMulator) just copy all files to a directory that should be named "UDO". The GEM version should be the application for files with the suffix `*.u*' so you shall do the neccessary changes in your desktop (Gemini, Thing, Ease, Magxdesk, ...). If you prefer the TTP version and you are using a command line shell (e.g. Mupfel by Stefan Eissing) copy or move `udo.ttp' to one of the directories that is part of $PATH (e.g. `\usr\bin'). If you have installed the ST-Guide you should copy or move UDO's hypertext (udo6eng.hyp and udo6eng.ref) to the directory that contains all your other hypertexts. That's all. 4.2 Installing the DOS version =============================== You need a 80386 processor at least to run UDO. UDO doesn't run on 80286 processors or processors of an older type and I won't compile versions for these old dinosaurs. If you find a program or batch file named SETUP or INSTALL in the archive please start it and follow the instructions. If the installa- tion fails, please go on reading this chapter. It failed? Ah, you haven't tested it yet? That's fine that you want to read all the text before you want to experiment. ;-) Unfortunately the installation of the DOS version is not trivial. Er, I think it is trivial but the experiences of the past have shown me that lots of people have problems installing UDO on a DOS PC although the installation is very simple. If you haven't heard anything of RSX and EMXRT until now I recommend to read the following two chapters completely. If UDO still refuses to run you have done something wrong or I haven't described the installa- tion process detailed enough. If you already know what RSX and EMXRT are good for, because you are using emTeX or the GNU utilities) you can skip the next chapter. 4.2.1 Installation of RSX and EMXRT ------------------------------------ OK, you haven't heard anything of RSX and EMXRT yet. That's not a shame. But if you won't know what RSX and EMXRT are good for after having read this chapter, you should feel ashamed. And if some RSX or EMXRT experts recognize some stupid stuff I should feel ashamed. Well, let's go... UDO was compiled with the GNU C Compiler (GCC), strictly speaking with EMX-GCC (ported by Eberhard Mattes). GCC is originally a Unix software and Unix has always used 32 bit software. Thus, the EMX-GCC makes 32 bit software, too. And now we have a problem, because you cannot run 32 bit software with DOS without using any tricks. EMXRT and RSX are responsible for these tricks. These "drivers" allow UDO to allocate huge blocks of memory. Because you have to use different tricks for DOS and Windows there are existing two different "drivers": EMXRT for DOS and OS/2, RSX for Windows. Please note: ü For running UDO exclusively in a DOS box with Windows 3.11/95 you will need only RSX. RSX, written by Rainer Schnitker, is a DPMI server for programs that were compiled with EMX-GCC or DJGPP. ü For running UDO under OS/2 or exclusively under DOS (without Windows) you will need only EMXRT. EMXRT ("emx runtime environ- ment"), written by Eberhard Mattes, is needed for running EMX-GCC compiled software. ü If you don't install neither RSX nor EMXRT there will be no chance to run UDO. It will simply print an error message. ü The installation of RSX and EMXRT is very easy. Just extract the archives with paths and enter two lines into the AUTOEXEC.BAT. ü RSX and EMXRT are no resident drivers. UDO will start them automatically. After UDO has finished the drivers terminate, too. ü If you haven't received the drivers (you haven't EMXRT.ZIP or DPMIGCC5.ZIP/RSX503RT.ZIP) and the UDO distribution doesn't contain the archives you can download them or you can request them by mail: FTP: Current version of EMXRT can be downloaded from ftp.uni- stuttgart.de/pub/systems/os2/emx-0.9b/ Current versions of RSX can be downloaded from: ftp.uni- bielefeld.de/pub/systems/msdos/misc/ Modem: You can download the files from the BBS called "Maus MK2 Iserlohn-Kalthof" (+49 2371 944925) from the "Gruppenprogrammteil UDO.PUB". Mail: Just send me a formatted floppy disk and a readdressed envelope and 2 DM (or a convertible amount of money) for postage. Let's talk about the installtion of RSX and EMXRT. Of course, you can install only one of the drivers if you run exclusively DOS or Windows. The following descriptions tells you how to install both drivers. In first place you have to extract the archives. Stop! It's importand that you extract the archives with paths! If you don't let your archiver generate paths nothing will function. I recommend to use UNZIP.EXE. If you extract the RSX archive a directory `RSX\' will be saved. If you extract EMXRT a directory `EMX\' will be saved. If you don't find these directories something went wrong. You can move the directories to any position of your file system. I recommend to move them to `C:\DRIVERS'. If this directory doesn't exist you have to create one. After having extracted the archives you have to edit your AUTOEXEC.BAT and to insert the following lines. If you have only installed EMXRT, insert the lines below "Only EMXRT" and so on: ü Only EMXRT: SET EMX=C:\DRIVERS\EMX\BIN\EMX.EXE ü EMXRT and RSX: SET EMX=C:\DRIVERS\EMX\BIN\EMX.EXE SET RSX=C:\DRIVERS\RSX\BIN\RSX.EXE ü Only RSX: SET EMX=C:\DRIVERS\RSX\BIN\RSX.EXE SET RSX=C:\DRIVERS\RSX\BIN\RSX.EXE If RSX and EMXRT haven't been installed in `C:\DRIVERS' you have to adjust the upper paths. I think you already know that changes of the AUTOEXEC.BAT are activated when rebooting your computer. Before you reboot your computer I just want to summarize what you have done until now: you have installed some files and you have inserted one or two lines into your AUTOEXEC.BAT. That's all. And now, reboot your computer. 4.2.2 Installation of UDO386.EXE --------------------------------- Let's talk of the easier part of the installation of UDO. The abridged version: extract the archive and add the UDO directory to PATH of your AUTOEXEC.BAT. But once more I will describe you the installation step by step: 1. Extract the UDO archvie with paths. If you won't find a directory named `UDO\' something went wrong. If you will find it move the directory named `UDO\' to any position of your file system. The following descriptions assume that you move `UDO\' to your root directory. 2. Now you have to let DOS find the executable: (a) Edit the AUTOEXEC.BAT and insert the following line: SET PATH=%PATH%;C:\UDO\BIN This meand that DOS and Windows will look for `UDO386.EXE' in this directory, too, when you have rebootet your computer. (b) If you don't like to extend your PATH you can move the executables of `C:\UDO\BIN' to any directory that's already listet in PATH. Using this method you don't have to reboot your computer. 4.3 Installing the Macintosh version ===================================== After having extracted the archive that contains the Macintosh version of UDO you can move UDO's files to any place of your file system you want to. In most cases this would be the "Programs" directory. UDO is available as a fat-binary so it will run both on a 68k Macintosh and a PowerPC Macintosh. If you want to save some disk space you may be smaller the program with a certain software. If you have access to the hypertext of UDO (`UDO6GER.HYP') you can read it with "Hyperion". Hyperion is a software written by Martin Osieka that can display ST-Guide hypertexts. When using Hyperion you should copy `UDO.HYP' to the Hyperion directory. 4.4 Installing the Unix versions ================================= After having extracted the archive copy the files of `bin/' to `/usr/local/bin' or any other directory of $PATH. Copy the manpage `udo.1' to `/usr/man/man1/'. To read the documentation of UDO with GNU Info convert the UDO source files to GNU Texinfo, run Makeinfo and copy the Info file to $INFOPATH. You have to edit $INFOPATH/dir to get access to the UDO Info files. Furthermore you should make some scripts or aliase to simplify calling UDO. The following script (named `'u2tex`') shows how to tell UDO that he shall convert the source file to LaTeX): #!bin/sh udo --tex -o ! $* You can make similar scripts for the other destination formats if you want. The UDO distribution already contains some scripts. Hint for users of Linux-SGML: My version doesn't contain all possible entities. Just take a look ate the Linuxdoc-SGML FAQ in the middle of this documentation if Linuxdoc-SGML prints an error message. ====================================================================== Chapter 5 Usage ====================================================================== In this chapter you will get to know which options you have to pass to the command line version and how to use the versions with a graphical user interface. 5.1 Command line version ========================= The command line version can be used identically on any operating system UDO is available for. Name ---- udo - convert files from UDO into different formats Synopsis -------- udo [-adDghHilmnpqrstvwWxy] source file udo [-adDghHilmnpqrstvwWxy] -o destination file source file Description ----------- UDO converts files from the UDO format into Apple-QuickView, ASCII, HTML, Texinfo, Linuxdoc-SGML, Manualpage, Pure-C-Help, Rich Text Format, ST-Guide, LaTeX, Turbo Vision Help or Windows Help. Using the first method UDO prints the destination format to the standard output (STDOUT) and error messages to the standard error output (STDERR). Using the second method UDO writes the destination format to the destination file and error messages to a log file with the suffix .ul?. You have to pass single options to UDO: -al isn't the same as -a -l! The name of the source file has to be the last option. Options ------- -a, --ascii The source file will be converted to ASCII. -D symbol Set the symbol `symbol' which can be tested in the source file with !ifset. -g, --helptag The source file will be converted to HP Helptag SGML. -h, --html The source file will be converted to HTML. -H, --hold You have to press a key before UDO finishes. -i, --texinfo The source file will be converted to GNU Texinfo. --lyx The source file will be converted to LyX. -l, --no-logfile When using the Option -o UDO doesn't save a log file. -m, --man The source file will be converted to a manualpage. -n, --nroff The source file will be converted to Nroff. -o F, --outfile F UDO writes the output into the file named "F". -p, --pchelp The source file will be converted to Pure C Help. -q, --quiet UDO won't print anything to STDOUT or STDERR. -r, --rtf The source file will be converted to RTF. -s, --stg The source file will be converted to ST-Guide. -t, --tex The source file will be converted to LaTeX. -v, --vision The source file will be converted to Turbo Vision Help. -w, --win The source file will be converted to Windows Help. -W, --no-warnings Warnings will be suppressed. Error messages will still be printed. -x, --linuxdoc The source file will be converted to Linuxdoc- SGML. -y, --no-hypfile UDO doesn't save a file with syllabification hints when using the option -o. --help Outputs a help page and quits. --test When using this option UDO won't save a destina- tion file. --tree When using this option UDO will save a file with the suffix .ut?. In this file you will see a tree with all files your source file includes. --verbose UDO will print some status information wile converting the source file. --version Outputs version information and quits UDO. Examples -------- udo file.u Convert the source file `file.u' to ASCII (default) and print the output to the standard output and error messages to the standard error output. udo --tex -o output.tex file.u Convert the source file `file.u' to LaTeX and write the output to the file named `output.tex'. Warnings, error messages and additional information will be written to the log file named `output.ult'. udo -s -y -l -o ! file.u Convert the source file `file.u' to ST-Guide and write the output to `file.stg'. UDO won't save a log file or a file with syllabi- fication patterns. Environment ----------- HOME UDO looks for the file udo.ini in your home directory if UDOPATH doesn't exist. LANG Sets the language UDO shall use for error messages if neither LC_ALL nor LC_MESSAGES exists. LC_ALL If this is set to `german' UDO prints German messages. If this variable doesn't exist LC_MESSAGES it tested instead. LC_MESSAGES See LC_ALL. If this variable doesn't exist, too, LANG is tested instead. UDOPATH UDO looks for the file udo.ini in the directory defined by this variable. If UDOPATH doesn't exist HOME is tested instead. Exit Status ----------- 0 Everything was OK. >0 An error has appeared. Author ------ Copyright (c) 1995, 1996, 1997 by Dirk Hagedorn (Dirk Hagedorn @ MK2, DirkHage@aol.com) 5.2 GEM version ================ The GEM version enables you to set the files and options by simply clicking the mouse. Furthermore you can define programs for editing and viewing files that can be started by the GEM version. The GEM version supports the VA protocoll, iconification and drag & drop. It runs with every AES: TOS, MultiTOS, Geneva, MagiC (Mac/PC) or STonX. While converting you can see the current status of UDO. Because of the AES calls the GEM version runs slower than the TTP version. If you want to convert large source files I recommend to use the TTP version. The usage of the GEM version is very easy. 5.2.1 GEM main dialog ---------------------- In the main dialog you can see several buttons and a menu bar. In the main dialog you choose the source file, the destination file and the destination format. By pressing the "Convert" button you start the conversion. The items of the menu bar open other dialogs in most cases. If not you can guess the sense of them by simply reading the menu item text. Two menu items have to be described: Dest/Start program: You can define a program for each destination format. E.g. you can define a program that converts the ST-Guide source files (made with UDO) into a ST-Guide hypertext, or a program that converts the LaTeX files into a DVI file. Dest/ST-Guide: If you choose this menu item UDO calls the ST- Guide and tells it to display the converted hypertext (source file name, suffix `.hyp)'). 5.2.2 GEM dialog `Settings' ---------------------------- After clicking the menu item "Options, Settings" this dialog appears. The sense of each button you can see in this dialog will be described now. ü Destination file: - Adjust: If this button is checked the GEM version will adjust the file name of the destination file when changing the destination format. How it is adjusted depends on the status of the following buttons: * Completely: UDO adjusts the name completely. * Name and suffix: UDO takes the name of the source file and adjusts the suffix according to the current desti- nation format. The path of the destination file isn't adjusted. * Only the suffix: UDO adjusts only the suffix of the destination file according to the current destination format. The path and the file name aren't adjusted. - View: If this button is checked UDO will call the destina- tion viewer after having converted the source file. ü Ask before: - Quitting UDO: If this button is checked UDO asks you before quitting it. - Overwriting file:If the destination file already exists UDO will ask if it should overwrite the file when starting the conversion. ü Options: - Save log file: Shall UDO save a log file that contains all error messages, warning messages and additional information (similar to the command line option --no-logfile)? - Save hyphen file: Shall UDO save a hyphen file with syllabi- fication patterns (similar to the command line option --no- hypfile)? - Save tree file: Shall UDO save a tree file where you can see the include file structure of your documentation (similar to the command line option --treefile)? - Verbose mode: Shall UDO display the status during the conversion (similar to the command line option --verbose)? - Suppress warnings: Shall UDO suppress warning messages in the log file (similar to the command line option --no- warnings)? 5.2.3 GEM dialog `Symbols' --------------------------- The GEM version enables you to set predefined symbols when starting the conversion. You can insert the text and choose which symbol has to be used by clicking the buttons on the left side. If an entry is checked UDO will use the text as a predefined symbol. 5.2.4 GEM dialog `External programs' ------------------------------------- This dialog looks very complicated and I must say that I have to change the design next time. In this dialog you can define the programs you can use for editing and viewing the source files and destination files or for converting the destination files. Please select the destination format in the upper half. In the lower half you can choose the program. If this program isn't a GEM application you should check the button "TOS program". If it is a GEM application and it supports VA_START you should check the "Supports VA_START" button. These settings are only used if UDO starts the programs itself. Finally you can edit the parameters UDO shall use when calling the programs. You can use placeholders for the name of the current source file and destination file. Click the "Hint" button to get more information. How UDO starts programs ü In first place UDO will look for an AV server. If AVSERVER is set inside the environment or Gemini or Thing are running, UDO tells them to start the program. ü If there's no AV server available UDO starts the programs itself. - If the program is an accessory the parameters will be transferred via VA_START. - If the program is already running and it supports VA_START, UDO will send a VA_START message to this program. - In all other cases UDO will start GEM applications with shel_write() and TOS programs with Pexec(). 5.3 Macintosh version ====================== The macintosh version looks more simply than the GEM version. All available options are combined in one dialog. If you don't start it with passing a UDO source file you can choose one by clicking the [Choose] or [AuswÌhlen] button. You can set the destination format by using one of the available formats that are listed inside the popup. If the destination files shouldn't be saved in the source folder you can choose a destination folder by clicking the second [Choose] or [AuswÌhlen] button. Which files UDO will save you can define by using the group of buttons. I hope you can guess the function of each button by reading the labels. The setting of the display popup ("Ausgabeanzeige") sets the speed of UDO. If you set it to "cooperative" ("kooperativ") you can work with other applications while UDO is converting the source file. The conversion can be started by clicking the [Output] or [Ausgeben] button. If your source file doesn't contain any error UDO quits without any comment. If there were errors the Macintosh version presents an error message with link to the log file. After having paid the shareware fee you will get a personalized keycode that you can enter into the dialog. If you enter the keycode correctly all limitations of the shareware version will be disabled. The documentation of UDO can be displayed anytime by pressing the help key or clicking the help menu if you have installed the hypertext viewer Hyperion (written by Martin Osieka) and if the hypertext UDO.HYP is installed in the guides folder of Hyperion. 5.4 UDO Shell for Windows ========================== The UDO shell for Windows ("UDOSH") makes it easier for you to use UDO with Windows. The shell can call UDO, editors and viewers and you can simple choose which destination format you want to use by clicking the mouse. The shell is distributed with the complete source code for Borland C++ and is described in a separate documentation. ====================================================================== Chapter 6 The syntax of UDO ====================================================================== 6.1 A short example ==================== Before going into details I want to show you how an UDO source file may look like. You can use this example to make your own source files if you want to. ----------------------------------------------------------------- ######################################## # @(#) An example for UDO # @(#) Dirk Hagedorn, 1996/04/16 ######################################## !stg @subject "Documentation/Utilities" !title A short example for !program UDO !date (!today) !author Dirk Hagedorn !use_auto_subtocs [info,html,stg,tvh,win,aqv] !use_auto_subsubtocs [info,html,stg,tvh,win,aqv] !no_effects [asc] !use_justified [asc] ######################################## !begin_document !maketitle !tableofcontents !node Automatic layout UDO layouts the source file automatically. You don't have to take care about spaces between two words because UDO enters line breaks on its own. Further more it doesn't make sense but doesn't disturb UDO if you enter more than one empty line between to paragraphs. Paragraphs are split by using empty lines or commands. !node A chapter This is the text of this chapter. Due to the switches inside the preamble it follows a table-of-contents-like list of all sections of this chapter. !subnode A section This is the text of this section. A ""subsubtoc"" will follow due to the switches inside the preamble, too. !subsubnode A subsection This is the text of this subsection. !end_document ----------------------------------------------------------------- Explanations ------------ At the beginning of this example you can see a comment. A comment is a line that begins with a `#' immediately. The next line is a special line. This line contains a special command for the ST-Guide. If you don't know the ST-Guide just add this line at the beginning of your source file so that are all the people are able to build a hypertext if they want to. Now the information for the title page and the headlines are set. !title and !program should make sense if you read them one after another. In this example it would be "An example for UDO". If you look at the line containing !date you will see the placeholder (!today) that is replaced by the current system date. You can set !date to April 16th, 1996 manually, if you want to. The preamble contains some switches. The first to switches are set for the output of "sub-tables-of-contents" in hypertexts. The abbrevia- tions of these hypertexts you will see inside the brackets. In a "subtoc" all subnodes of a node are printed like a table of contents so that readers of a hypertext are enabled to directly switch to an interesting subnode. The switch !no_effects [asc] suppresses the usage of Usenet text effect commands like stars for bold and slashes for italic text. The switch !use_justified [asc] tells UDO to layout the ASCII file with justified text. The command !begin_document tells UDO that now the main part of the document begins. This command has to be part of any source file! In first place we output the title page that is built with the information set in the preamble of this example. You should use !maketitle directly after !begin_document if you use it. It's possible to use it later but I don't think that it would work without problems. Then we want that UDO prints a table of contents. There you can see all chapters, sections and subsections of the source file. Like !maketitle you should use !tableofcontents directly after !begin_document or !maketitle if you use this command. Now we can enter the first chapter of our text. Chapters are marked with !node. Please read the contents of this chapter that contains additional information. The following lines demonstrate how to use chapters, sections and subsections. You should also read the text of these chapters to get more information. Finally we end our text with the command !end_document. This command has to be part of every source file and should be the last command of a source file! 6.2 Basics =========== 6.2.1 Let's talk about text, Baby! ----------------------------------- UDO expects a text file that you can edit with every ASCII editor. You should use only printable characters. That means you shouldn't use any characters below "space" except ASCII 9 (tab), ASCII 10 (line feed) and ASCII 13 (carriage return). A line of a source file shouldn't contain more than 512 characters. UDO layouts the destination file itself. That means that it fills in spaces between words and lines between paragraphs: Words are characters that are divided by one or more blank or tab. UDO prints words divided by one blank. Paragraphs consist of words. Paragraphs are divided by one or more empty line(s) or UDO commands. UDO divides paragraphs by one empty line when printing the destination file. You can compose the source file using different charsets. UDO supports the following character sets: ü Atari ST (!code_tos) ü Apple Macintosh (!code_mac) ü HP Roman 8 (!code_hp8) ü IBM PC (!code_dos) ü ISO Latin 1, Windows ANSI (!code_iso) When UDO starts the conversion it excepts the character set that is used on the current operating system. If you want to convert source files that use characters from a different operating system you have to tell it to UDO by using the upper commands. Additional information can be found in the chapter "Special characters". 6.2.2 Commands, switches and placeholders ------------------------------------------ Commands: An UDO command begins with a single "!" at the beginning of a line, it may be indented by spaces or tabs. A command tells UDO to do something where you used it e.g. to output the table of contents with !tableofcontents. Switches: An UDO switch begins with a single "!" at the beginning of a line, it may be indented by spaces or tabs. A switch tells UDO how to handle some commands e.g. !language english that switches the language of the destination file to English so that UDO will print "Appendix" instead of "Anhang". Placeholders: An UDO placeholder begins with a "(!" and ends with a single ")". A placeholder is replaced by certain char- acters e.g. `(!B)' by `{\bf' for LaTeX. You can use placeholders wherever you want. 6.2.3 Comments --------------- A source file can contain comments. UDO ignores a line if the first character of a line is a `#'. This character mustn't be indented by spaces or tabs! Inside a verbatim environment or raw environment you cannot use comments because UDO prints every line of such an environment. 6.2.4 Preamble and main part ----------------------------- Each source file has to contain a preamble and a main part. In the preamble you define general information about the source file like information for the title page or the switches that tell UDO how to convert the source file. The preamble ends with the command !begin_document. The main part contains the text structured into chapters, sections or subsections. The main part ends with the command !end_document. 6.2.5 Environments ------------------- An environment is a part of a source file that has to be converted in a special way. Environments will be started with !begin_ and finished with !end_. The commands have to be the first words of a line. They may be indented by spaces or tabs. UDO offers you a large range of environments that will help you to layout your text and to insert special commands: appendix environment: appendix center environment: centred text description environment: descriptions document environment: documentation contents enumerate environment: enumerations flushleft environment: left justified text flushright environment: right justified text itemize environment: itemizations quote environment: indented text raw environment: special commands for the destination format table environment: tables verbatim environment: preformatted text xlist environment: lists How the text of an environment is formatted you can find in the according sections. 6.3 Structuring ================ In this chapter you will get to know what commands are offered to structure your documentation. 6.3.1 Title page ----------------- Using the command !maketitle you can tell UDO to generate a title page built with information you set in the preamble with the following commands: !title: The title of the documentation e.g. "The guide to" or "The introduction to". !program: The name of the software or theme you describe inside the documentation. !programimage: The filename of an image UDO shall display on the title page instead of !program. !version: This is used for version information e.g. "Release 6" or "Version 42". !date: The date you have written the documentation or the program. !author: The name of the author of the documentation. !authorimage: The filename of an image UDO shall display on the title page above the name of the author. !street: The street where the author lives. Optionally you can enter any other text that will be displayed below the name of the author on the title page. !town: The town where the author lives. Optionally you can enter any other text that will be displayed below the street on the title page. !country: The country where the author lives. Optionally you can enter any other text that will be displayed below the town on the title page. !email: The email address(es) of the author. You can use this command up to five time if you have several email addresses. You don't have to use all commands but you should use one command at least if you are using the command !maketitle. When used !maketitle should only be used directly after !begin_document. To use this command at another place of the source file is allowed but there could be problems. The title page will be printed on a single page when converting to ST-Guide or Windows Help. This is a great help for people with small screens. From the title page you will be able to jump to the table of contents. Converting to LaTeX UDO generates a single page using the title page environment built with the information from the preamble. If you want to make your own title page you have to use some tricks. You will find an example inside the UDO distribution that shows you how to make userdefined title pages. 6.3.2 Tables of contents ------------------------- Using the command !tableofcontents you can tell UDO to generate a table of contents that lists all chapters, sections and subsections of the source file. You should use !tableofcontents directly after !maketitle or !begin_document to avoid problems. By using the switches !no_toc_subnodes, !no_toc_subsubnodes and !no_toc_subsubsubnodes you can decrease the size of the table of contents. This is useful when writing large hypertexts. If you want to list all sections of a chapter, all subsections of section or all paragraphs of a subsection you can output this so called "sub-table of contents" with the commands called !subtoc, !subsubtoc and !subsubsubtoc. This is useful for hypertexts where you then have the possibility to switch directly to an interesting section or subsection. UDO enables you to automatize the output of these "subtoc's" using the switches !use_auto_subtocs, !use_auto_subsubtocs and !use_auto_subsubsubtocs. If you use the upper switches to print subtocs automatically but you don't want to print them in specific chapters you can insert the commands !ignore_subtoc, !ignore_subsubtoc or !ignore_subsubsubtoc. If a chapter contains one of these commands there will be printed no table of contents neither automatically nor manually by using !subtoc etc. Summary of all commands and switches ------------------------------------ !tableofcontents: Prints the table of contents on a separate page. !toc: Prints the table of contents inside the text. !subtoc: Prints all sections of a chapter. !subsubtoc: Prints all subsections of a section. !subsubsubtoc: Prints all paragraphs of a subsection. !no_toc_subnodes: Tells UDO that it has to print only the chapter names inside the table of contents. !no_toc_subsubnodes: The table of contents lists only the chapters and sections. !no_toc_subsubsubnodes: The table of contents lists only the chapters, sections and subsections. !use_auto_subtocs: Print all sections of a chapter automatically. !use_auto_subsubtocs: Print all subsections of a section automatically. !use_auto_subsubsubtocs: Print all paragraphs of a subsection automatically. !ignore_subtoc: Don't print the sections of the current chapter. !ignore_subsubtoc: Don't print the subsections of the current section. !ignore_subsubsubtoc: Don't print the paragraphs of the current subsection. Please note: 1. When converting to HTML the title page and the table of contents will be printed in the file you passed via the command line. 2. When converting to RTF no table of contents will be generated! You should make this with the functions of your text processor that is used to import the converted RTF file. 6.3.3 Chapters, sections, subsections and paragraphs ----------------------------------------------------- UDO offers you four layers for structuring your documentation. These layers are called chapters, sections, subsections and paragraphs. Using the command !node you tell UDO that a new chapter begins and you tell it how the chapter is named. The commands !subnode, !subsubnode and !subsubsubnode do the same for a section, subsection and paragraph. Watch this example (without text) to understand what I want to say: !node A chapter !subnode A section !subsubnode A subsection !subsubsubnode A paragraph !node And a different chapter The table of contents should look like this: 1 A chapter 1.1 A section 1.1.1 A subsection 1.1.1.1 A Paragraph 2 And a different chapter Windows Help and ST-Guide may display text in dialog boxes, too. These so called popup nodes can be used with the following commands: ü !pnode for popup chapters, ü !psubnode for popup sections, ü !psubsubnode for popup subsections and ü !psubsubsubnode for popup paragraphs Furthermore you can create chapters that don't appear in the table of contents. Use these commands... ü !node* for chapters, ü !subnode* for sections, ü !subsubnode* for subsections, ü !subsubsubnode* for paragraphs ü !pnode* for popup chapters, ü !psubnode* for popup sections, ü !psubsubnode* for popup subsections and ü !psubsubsubnode* for popup paragraphs. Please note: 1. Chapters that aren't listed in the table of contents aren't numbered, too. UDO will create hypertext links to them as it does for all other chapters. 2. UDO enumerates the chapters automatically. If you want to display the chapter names without numbers you can use the switch !no_numbers inside the preamble. 6.3.4 Appendix --------------- UDO can manage one(!) appendix. The contents of the appendix has to be used inside the appendix environment. This environment is started with !begin_appendix and finished with !end_appendix. Chapters that are part of the appendix are enumerated using letters instead of numbers. A short example: !node A chapter outside the appendix !begin_appendix !node A chapter !subnode A section !subsubnode A subsection !subsubsubnode A paragraph !end_appendix The table of contents should look like this: 5 A chapter outside the appendix Appendix A A chapter A.1 A section A.1.1 A subsection A.1.1.1 A paragraph Please note: 1. You should use the appendix at the end of your source file. In other words !end_appendix should be the last but one command before !end_document. You shouldn't use any additional chapters behind !end_appendix because UDO will get confused especially while enumerating the chapters. 2. Because UDO uses letters for creating the numbers for the chapters of the appendix you shouldn't use more than 26 chapters inside the appendix. 6.4 Emphasising text ===================== In this section you will get to know how to layout passages in different ways. UDO supports centred, left justified, right justified and indented text, different kinds of lists, environments for preformatted text and tables. Furthermore you can use different text styles and footnotes. 6.4.1 Itemizations ------------------- You can use the itemize environment for itemizations where every single item is marked with a bullet, star, dash or point. The itemize environment is started with !begin_itemize and finished with !end_itemize. Each item has to be marked with the !item command. You can use the itemize environment inside other environments or inside another itemize environment. This short example shows how to write a simple itemize environment: !begin_itemize !item This is the first item. !item This is the second item with a little bit more text to demonstrate how UDO formats an itemization. This is the second paragraph of the second item of the itemize environment. !item This is the last item. !end_itemize ... will be printed this way: ü This is the first item. ü This is the second item with a little bit more text to demon- strate how UDO formats an itemization. This is the second paragraph of the second item of the itemize environment. ü This is the last item. And this example, where an itemize environment is used inside another one ... !begin_itemize !item This is the first item of the outer itemize environment. !item This is the second item of the outer itemize environment. !begin_itemize !item This is the 1st item of the inner one. !item This is the 2nd item of the inner one. !end_itemize !item This is the third item of the outer itemize environment. !end_itemize ... will be printed this way: ü This is the first item of the outer itemize environment. ü This is the second item of the outer itemize environment. - This is the 1st item of the inner one. - This is the 2nd item of the inner one. ü This is the third item of the outer itemize environment. UDO separates the text of each item by an empty line. In some cases it's not a good idea to separate the items e.g. if an item contains only some text. In this case it would be better to suppress the empty lines to get a compressed environment. For printing compressed environment UDO offers you the command named !short you can add to the !begin_itemize command. If you add !short UDO won't separate the items by inserting empty lines. Furthermore in all environments you use inside this itemize environment no empty lines will be printed. The following two examples show how to use the !short command and which effects this command has. The first example doesn't, the second one uses !short: Without !short... !begin_itemize !item Item 1 !item Item 2 !item Item 3 !end_itemize ... will be displayed this way: ü Item 1 ü Item 2 ü Item 3 With !short... !begin_itemize !short !item Item 1 !item Item 2 !item Item 3 !end_itemize ... will be displayed this way: ü Item 1 ü Item 2 ü Item 3 If you can't see any difference the destination format doesn't allow it to suppress the item separation. Please note: 1. The items of the first itemize environment will be marked with a bullet that is defined on different positions inside the character set of each operating system. 2. If you use the switch !no_umlaute inside the preamble of the source file the items of the first itemize environment will be marked with an `o' instead of a bullet. 6.4.2 Enumerations ------------------- The enumerate environment is useful for lists where the items have to be enumerated with numbers or letters. It is started with !begin_enumerate and finished with !end_enumerate. Each item has to be marked with !item. You can use the itemize environment inside other environments or inside another itemize environment. This short example shows how to write a simple itemize environment: UDO offers you the following environments: !begin_enumerate !item itemize environment !item enumerate environment (discussed in this section) !item description environment !item xlist environment !end_enumerate ... will be displayed this way: UDO offers you the following environments: 1. itemize environment 2. enumerate environment (discussed in this section) 3. description environment 4. xlist environment In the following example the enumerate environment is used twice and it will be compressed because of the usage of !short: !begin_enumerate !short !item This is the first item of the outer enumerate environment. !item This is the second item of the outer enumerate environment. !begin_enumerate !item Item 1 of the inner environment. !item Item 2 of the inner environment. !end_enumerate !item This is the third item of the outer enumerate environment. !end_enumerate ... becomes to: 1. This is the first item of the outer enumerate environment. 2. This is the second item of the outer enumerate environment. (a) Item 1 of the inner environment. (b) Item 2 of the inner environment. 3. This is the third item of the outer enumerate environment. Please note: 1. UDO doesn't enumerate the items for all destination formats. E.g. HTML and LaTeX enumerate the items themselves so you have to be cautious with using text like "see item 1" or "see point b)". 2. The third layer of enumerate environments will be indented deeper than the other layers because Roman numbers need a little bit more space. 3. Because the second layer is enumerated with letters you shouldn't use more than 26 items. 4. A description of the !short command is part of the chapter "Itemizations". 6.4.3 Descriptions ------------------- Use the description environment for describing some words. Start the environment with !begin_description and finish it using !end_description. A word that has to be described is used with the !item [ ] command inside brackets and will be displayed with bold text. The description environment can be used inside other (description) en- vironments. This example... UDO offers you the following environments: !begin_description !item [the itemize environment] for itemized lists, !item [the enumerate environment] for enumerated lists, !item [the description environment] for descriptions and !item [the xlist environment] for lists !end_description ... will be display this way: UDO offers you the following environments: the itemize environment for simple lists, the enumerate environment for enumerated lists, the description environment for descriptions and the xlist environment for lists In this example the description environment is used inside another one and the !short is used, too: !begin_description !short !item [Item 1] of the outer description environment !item [Item 2] of the outer description environment !begin_description !item [Item 1] of the inner environment. !item [Item 2] of the inner environment. !end_description !item [Item 3] of the outer description environment !end_description ... becomes to: Item 1 of the outer description environment Item 2 of the outer description environment Item 1 of the inner environment. Item 2 of the inner environment. Item 3 of the outer description environment Please note: 1. If the word that shall be displayed in bold text contains a "]" you have to quote it with an exclamation mark to tell UDO that it has to be printed in bold text, too. 2. The HTML version of your source file will print the descriptions in bold text, too, even if this not typical for HTML. The next versions of UDO will offer a command to disable the bold text inside descriptions for HTML. 3. A description of the !short command is part of the chapter "Itemizations". 6.4.4 Lists ------------ Like the description environment this set of commands is useful to describe words. Using this environment the description of each word is displayed beneath one another. The xlist environment starts with !begin_xlist [...] and finishes with !end_xlist. You have to tell UDO in brackets how wide it should indent the descriptions of each item. Usually you use the longest word in brackets. Each word that has to be described has to used inside the brackets of the !item [ ] command. You can use the xlist environment inside other (xlist) environments, too. This short example... UDO offers you the following environments: !begin_xlist [description environment:] !item [itemize environment:] for itemizations !item [enumerate environment:] for enumerations !item [description environment:] for descriptions !item [xlist environment:] for lists (discussed in this section) !end_xlist ... will be displayed this way: UDO offers you the following environments: itemize environment: for itemizations enumerate environment: for enumerations description environment: for descriptions xlist environment: for lists (discussed in this section) The command !short can also be used for xlist environments. To get a compressed list just add !short at the end of the line that contains !begin_xlist. Once more a short example: !begin_xlist [description:] !short !item [itemize:] Itemizations !item [enumerate:] Enumerations !item [description:] Descriptions !item [xlist:] Lists !end_xlist ... will be displayed this way: itemize: Itemizations enumerate: Enumerations description: Descriptions xlist: Lists Since Release 6 UDO offers three additional environments that are familiar with the xlist environment. In contrast to the xlist environ- ment the items will be displayed in bold, italic or typewritered text. 1. When using the blist environment (bold list) the items will be displayed in bold text. A blist environment will be started with !begin_blist and finished with !end_blist. 2. When using the ilist environment (italic list) the items will be displayed in italic text. A blist environment will be started with !begin_ilist and finished with !end_ilist. 3. When using the tlist environment (typewritered list) the items will be displayed in typewritered text. A tlist environment will be started with !begin_tlist and finished with !end_tlist. The following example shall demonstrate the results: !begin_xlist [typewritered:] !item [normal:] !.. !end_xlist !begin_blist [typewritered:] !item [bold:] !.. !end_blist !begin_ilist [typewritered:] !item [italic:] !.. !end_ilist !begin_tlist [typewritered:] !item [typewritered:] !.. !end_tlist ... will be displayed this way: normal: ... bold: ... italic: ... typewritered: ... You have to notice some aspects: 1. If the text inside the brackets contains a "]" you have to quote it with an exclamation mark so that UDO will recognize that this "]" shall be part of the item and shall be displayed on the "left side". 2. HTML, Linuxdoc-SGML and Texinfo don't support an environment like UDO's xlist environment. In these formats the xlist environments are displayed like a description environment by default. But if you use the switch !use_xlist inside the preamble UDO will print xlist environments like in ASCII, but with preformatted text. 3. UDO doesn't know the character widths when converting the source file to RTF and Windows Help. If the indents are too wide you can adjust the indent by using the commands !rtf_charwidth and !win_charwidth. 4. A description of the !short command is part of the chapter "Itemizations". 6.4.5 Centred text ------------------- Lines that are part of a center environment will be displayed centred if the destination format centred text. You can use the center environment inside other environments. You can also use it inside another center environment, even this may be senseless. If you use other environments inside a center environment they will be layouted like in all other cases. Only when the center environment is the active one text will be printed centred. If the following example isn't centred the current documentation format doesn't allow it to use centred text. !begin_center A centred line. A centred paragraph with two source lines. The Guide to (!nl) UDO !end_center ... will be printed in this way: A centred line. A centred paragraph with two source lines. The Guide to UDO You see that UDO layouts paragraphs of a center environment, too. To insert a manual line break use the (!nl) command. 6.4.6 Right justified text --------------------------- Lines that are part of a flushright environment will be displayed right justified if the destination format supports right justified text. You can use the flushright environment inside other environments. You can also use it inside another flushright environment, even this may be senseless. If you use other environments inside a flushright environment they will be layouted like in all other cases. Only when the flushright en- vironment is the active one text will be printed right justified. If the following example isn't printed right justified the current documentation format doesn't allow it to use right justified text. !begin_flushright A right justified line. A right justified paragraph with two source lines. The Guide to (!nl) UDO !end_flushright ... will be printed in this way: A right justified line. A right justified paragraph with two source lines. The Guide to UDO You see that UDO layouts paragraphs of a flushright environment, too. To insert a manual line break use the (!nl) command. 6.4.7 Left justified text -------------------------- Lines that are part of a flushleft environment will be displayed left justified without justification. Er, do you understand that? No? OK, one more try. If you use the switch !use_justified UDO adjusts the lines by inserting spaces between the words so that you have a proper right margin. But UDO won't insert spaces between words of a flushleft environment. You can use the flushleft environment inside other environments. You can also use it inside another flushleft environment, even this may be senseless. If you use other environments inside a flushleft environment they will be layouted like in all other cases. Only when the flushleft environ- ment is the active one text will be printed without justification. This short example... !begin_flushleft A left justified line. A left justified paragraph that will be printed without justification. This senseless sentence is added to demonstrate the missing justification. The Guide to (!nl) UDO !end_flushleft ... will be printed in this way: A left justified line. A left justified paragraph that will be printed without justification. This senseless sentence is added to demonstrate the missing justification. The Guide to UDO You see that UDO layouts paragraphs of a flushleft environment, too. To insert a manual line break use the (!nl) command. 6.4.8 Indented paragraphs -------------------------- To display indented paragraphs you can use the quote environment which is started with !begin_quote and finished with !end_quote. You can use the quote environment inside another quote environment or inside other environments. This environment is useful to emphasize passages. This effect is used in the following example: !begin_quote This paragraph is used inside a quote environment and will be displayed indented. !end_quote ... becomes to: This paragraph is used inside a quote environment and will be displayed indented. Please note: When converting to HTML the tag
is used. Netscape and CAB display paragraphs indented but Mosaic displays them just with another font. 6.4.9 Preformatted text ------------------------ UDO layouts the text of the source file on its own. But sometimes you don't want that because you want to display preformatted things like parts of a source code or something else. To display preformatted text you can use the verbatim environment that is started with !begin_verbatim and finished with !end_verbatim. No UDO commands (except !end_verbatim) or placeholders will be converted. Text inside this environment will be indented like normal text. When converting into LaTeX the commands of UDO will be just replaced by the LaTeX commands \begin{verbatim} and \end{verbatim}. When converting to another format UDO adjusts special chars and displays the text with a non-proportional font. If the lines of the verbatim environment contain tabs (ASCII 9) UDO will replace them by spaces according to the !tabwidth setting. Because no commands inside a verbatim environment are noticed you cannot use the !include command inside this environment. To enable you to include an external file and display it as it would be inside a verbatim environment UDO offers you the command !vinclude. This command is a mixture of !begin_verbatim, !include and !end_verbatim. To write special commands for the destination format you cannot use this environment. You have to use the raw environment instead. Please note: 1. Because the text of a verbatim environment is indented like normal text you shouldn't use extra spaces at the beginning of each line. 2. The difference between the raw environment and the verbatim envi- ronment is that text of a verbatim environment will be displayed an you entered it, but text of a raw environment will be saved into the destination file as you entered it. 6.4.10 Footnotes ----------------- Text that is used between (!N) and (!n) will be shown as a footnote when converting to a format that supports footnotes. Otherwise (!N) will be replaced by ` (', (!n) will be replaced by `)'. Important hint: Before (!N) you shouldn't use a blank. If you do so the footnote mark would "fly" without context or before the `(' you could read two blanks. This example... UDO(!N)Universal Document(!n) ... becomes to: UDO (Universal Document) Footnotes are supported by these formats: ü LaTeX ü Linuxdoc-SGML ü LyX ü Texinfo ü RTF Please note: 1. I'm a bit unlucky that UDO just prints brackets if the destina- tion format doesn't support footnotes. It will be better if UDO saves the footnote text and prints it at the end of a chapter or page. Unfortunately this is a very tricky problem that cannot be solved in some days. 2. Don't forget not to use a space or tab before (!N). 6.4.11 Text styles ------------------- UDO enables you to set text styles right inside the source file. At the moment UDO supports bold, italic, underlined, preformatted and non-proportional text. If you want to display a single word or some words in a certain text style you have to use them between the according placeholders. Look, how the upper paragraph was made: At the moment UDO supports (!B)bold(!b), (!I)italic(!i), (!U)underlined(!u), (!V)preformatted(!v) and (!T)non-proportional text(!t). In this table you will see in which way the placeholders will be replaced: +------+-------+----------+-------------+------+---------+--------+ | UDO | ASCII | ST-Guide | LaTeX | RTF | WinHelp | HTML | +------+-------+----------+-------------+------+---------+--------+ | (!B) | * | @{B} | {\bf | {\b | {\b | | | (!b) | * | @{b} | } | } | } | | +------+-------+----------+-------------+------+---------+--------+ | (!I) | / | @{I} | {\it | {\i | {\i | | | (!i) | / | @{i} | } | } | } | | +------+-------+----------+-------------+------+---------+--------+ | (!U) | _ | @{U} | {\underline | {\ul | {\ul | | | (!u) | _ | @{u} | } | } | } | | +------+-------+----------+-------------+------+---------+--------+ | (!V) | | | \verb+ | {\f1 | {\f1 | 
  |
 | (!v) |       |          | +           | }    | }       |
| +------+-------+----------+-------------+------+---------+--------+ | (!T) | | | {\tt | {\f1 | {\f1 | | | (!t) | | | } | } | } | | +------+-------+----------+-------------+------+---------+--------+ As you see here for the ASCII format there will be used the text style commands as they are used in Usenet. If you don't like them you can use the switch called !no_effects to suppress them. Use !no_effects [asc] to suppress the text style commands when converting to ASCII. Please note: Definitions are great for programming user-defined text styles. It's for sure that you need some knowledge about the destina- tion forma to do this. The following example show how to use ghosted text which is available for the ST-Guide: !ifdest [stg] !define G @{G} !define g @{g} !else !define G !define g !endif Normal and (!G)ghosted(!g). 6.4.12 Tables -------------- Since Release 5 you are able to print simple tables with UDO. You can define the justification of the columns and where UDO shall print vertical and/or horizontal lines. To print tables with UDO you need the following commands: 1. !table_caption 2. !begin_table [...] {!hline} 3. !end_table 4. !hline 5. !! The command !table_caption defines the title of the next table. It has to be used before the table environment, not inside this environment! The command !begin_table starts a table, !end_table finishes and prints the table. After !begin_table you can define the justification of the table columns and the usage of vertical lines. Use `c' for a centred row, `l' for a left justified row, `r' for a right justified row and `|' for vertical lines inside brackets. If you add a !hline command to this line the table starts with a horizontal line. After having described the layout of the table with the upper line you can insert the cells of the table. You have to insert a column in one source line and you have to divide the cells by using `!!'. If you want to insert a horizontal line you can use the !hline command. !hline has to be at the beginning of the line and it has to be the only command of this line. Here you will see a short example that demonstrates the usage of the upper described commands: !table_caption Tables with UDO !begin_table [|l|c|r|] !hline upper left !! up !! upper right lower left cell !! lower cell !! lower right cell !hline !end_table This example prints a table with two rows and three columns. The first column is left justified, the second columns is centred and the third columns is printed right justified: +-----------------+------------+------------------+ | upper left | up | upper right | | lower left cell | lower cell | lower right cell | +-----------------+------------+------------------+ Table 4: Tables with UDO Because I used a `|' before and after every column they are divided by vertical lines. The table starts with a horizontal line because the !hline command was added at the end of !begin_table. Finally the table ends with a horizontal line because the !hline command is used right before !end_table. The following example shows the upper table without any lines: upper left up upper right lower left cell lower cell lower right cell Table 5: Another example UDO offers you a switch called !use_ansi_tables. If you use this switch inside the preamble the lines of the table are printed by using some characters of the IBM PC graphic character set instead of +, - and | when converting into an ASCII like format like ASCII or ST- Guide. This switch has no effect if you convert to Windows Help, RTF, HTML or LaTeX. Please note: ü Tables are always printed centred. ü HTML doesn't allow to define where to use lines. If you use the !hline command at the end of !begin_table the table is printed via frame=box. If you don't use !hline it is printed without any lines. ü Windows Help doesn't allow it to print centred tables or to print lines where you want to. If you use !hline in the !begin_table line all cells will be printed with a box. If you don't use !hline there will be no line at all in this table. ü Converting to ST-Guide the lines of a table are generated with @line. It's not possible to use more than one vertical line between columns or more than one horizontal line. ü Inside the cells you can use all other UDO commands like text styles, links or indices. 6.5 Special characters ======================= 6.5.1 Double quotes -------------------- Double quotes of the source file will be converted to typographical quotes if they are supported by the destination format. The following ASCII simulation demonstrates how it works: Double ""quotes"" 66 99 Double quotes If you want to display two quotes you have to use ("")text("") instead. Please note: 1. The conversion of these double quotes can be suppressed using the switch called !no_quotes [ ]. 2. When converting to RTF special RTF commands will be used. 6.5.2 Double apostrophes ------------------------- Like double quotes UDO can convert double apostrophes into typographi- cal apostrophes: double ''apostrophes'' will become double `apostrophes' If you want to display two apostrophes you have to use ('')text('') instead. Please note: The switch !no_quotes [ ] switches off the conversion of these double apostrophes, too. 6.5.3 Non breaking spaces -------------------------- If you want to insert non-breaking spaces between two words you have to use the tilde (~). Non-breaking spaces are also useful to stop UDO and the other formats from breaking lines between two words. Converting to an ASCII format UDO replaces this tildes by blanks. Converting to other formats UDO replaces this tildes by commands that have the same effect. LaTeX: ~ HTML:   RTF: \~ WinHelp: \~ If you want to display a tilde you have to use !~ instead. Please note: If you use a tilde inside an external link UDO won't convert it. 6.5.4 Dashs ------------ UDO supports - did you think anything else - dashs like in this sentence. Dashs are supported by LaTeX, Windows Help and RTF. Converting to other formats UDO will replace `---' and `--' by a single `-'. If you want to display three or two `-' you have to use (---) or (--). 6.5.5 Converting 8 bit chars ----------------------------- In an UDO source file you can use "higher" characters without having to know how a character has to look like in a destination format like LaTeX or Windows Help. So you can enter a German `Þ' without any fear, UDO converts it for you and it knows that this has to be ß for HTML or {\ss} for LaTeX. UDO expects files containing chars of the system charset of your operating system. If you run UDO on a MS-DOS computer UDO expects text files that are written with the IBM PC character set by default. If UDO runs on an Atari computer UDO will expect the TOS character set by default. But UDO can manage file that are written with another character set, too. You have simply to tell UDO which character set your source file uses with the following commands: !code_dos: IBM-PC, MS-DOS !code_hp8: HP Roman 8 !code_iso: ISO Latin 1, Windows ANSI !code_mac: Apple Macintosh !code_tos: Atari ST There are some things you have to remember. Some character sets contain characters that aren't available in another one. So you shouldn't use characters from the PC graphic character set or the Hebraic characters of the Atari character set because they can't be printed in formats like LaTeX, Windows Help, RTF or HTML. In this case UDO prints an error message. You should remove these characters from your source file and find another solution. If source files are converted that don't use the character set of the operating system UDO is running on the limitations are even higher. In the first step UDO will convert the characters into ISO Latin 1. In the second step UDO will convert the ISO Latin 1 characters into the character set of the current operating system. In some cases there's is no possibility to convert the characters without any loss. In such a case UDO will print an error message. Please note: If I've forgotten any character or a character is converted in a wrong way please send a bug report! 6.6 Syllabification ==================== UDO supports a semi-automatic syllabification for ASCII, ST-Guide, Pure C Help and Manualpage. "Semi-automatic" means that you have to tell UDO at which position a word can be divided into two pieces. You have two possibilities to set the syllabification patterns: 1. Local definition ("!-") 2. Global definition using the !hyphen command When converting to LaTeX the marks will be replaced by "\-". Then LaTeX knows that a word can be split at these positions. When converting to RTF, Windows Help and HTML the marks are deleted. If you want to display !- you have to use !/-. 6.6.1 Local definition of syllabification patterns --------------------------------------------------- You can set the syllabification marks in the source file using "!-". At these marks UDO is allowed to split up a word. A short example: semi-automatic syl!-labi!-fi!-cation When converting to LaTeX UDO replaces all "!-" by "\-". So it would look like "syl\-labi\-fi\-cation". Converting to ASCII, ST-Guide, Pure C Help and Manualpage the word is split up into different parts if it doesn't have enough place at the end of a line. So it can look like "syl- labification", "syllabi- fication" or "syllabifi- cation" When converting to other formats the marks are simply deleted. 6.6.2 Global definition of syllabification patterns ---------------------------------------------------- You can set these marks at the beginning of a source file with the !hyphen command for often used words. "Global" means that you only have to define the marks once. If a word hasn't enough place at the end of a line when converting to ASCII, ST-Guide, Pure C Help or Manualpage UDO looks for a global definition in its internal list. In the following example I expect that the word "documentation" is used many times in your source file: !hyphen docu!-men!-ta!-tion 6.6.3 Short lines ------------------ When converting to ASCII, Pure C Help, ST-Guide or Manualpage UDO can generate a relative regular right margin due to its semi-automatic syllabification. The right margin becomes irregular when long words haven't enough place at the end of a line. UDO will print a warning containing the specific word and you should try to insert some syllabification marks. Please note: The command !sloppy switches of these warnings, !fussy switches them back on. While developing a documentation you should use !sloppy. At the end of developing a text you should comment this switch and you should look after warnings according short lines. 6.7 Images =========== UDO enables you to include images into your destination format if it supports images like ST-Guide, LaTeX, HTML and Windows Help. This chapter explains how to include images into a destination file and what destination commands UDO generates. To display an image you can use the !image command. You have to add the name of the image without suffix and an optional image title. To display images right inside the text you can use the placeholder (!img ..) when converting into Windows Help or HTML. The other formats don't allow to use images inside the text or it is so difficult that UDO can't automatize it. Since Release 6 images will not be centred in all cases. To display a centred image you have to insert the !image command into a center en- vironment. To display a right justified image you have to insert the !image command inside a flushright environment. In all other cases images will be displayed left justified. 6.7.1 *.img & ST-Guide ----------------------- Example: !image tiger A tiger UDO opens the file tiger.img and reads the size of this image. A special ST-Guide command called @limage is generated and the needed parameters are calculated due to the information of the GEM image header. If you want to display a subtitle add it right after the name of the image file. This subtitle will look like "(Figure x: A tiger)". 6.7.2 *.img & Lindner-TeX -------------------------- If you are using Lindner-TeX and you want to include a GEM image into your DVI file you have to add !tex_lindner to your preamble. UDO replaces the tool called IMGTOTEX that is part of Lindner-TeX. UDO has all functions of this tool built in. To set the size of an image you have to use the !tex_dpi command. An example: !tex_dpi 100 !image tiger A GEM image UDO reads in the header of tiger.img, calculates its size and adjusts the header to 100 dpi. In the destination file a TeX macro will be generated that includes this image and displays it with 100 dpi. Please note: Using 100 dpi screenshots are displayed in the original screen size on my HP DeskJet 510. !tex_dpi can be used before any image. If you are using an image more than once you shouldn't try to display it in different resolutions. Use a copy of your image instead and display the original one with the first and the copy with the second resolution. 6.7.3 *.img & CS-TeX/MultiTeX ------------------------------ If you are using CS-TeX or MultiTeX and you want to include a GEM image into your DVI file you have to add !tex_strunk to your preamble. Because the drivers of CS-TeX support the macros of Lindner-TeX the same is done here as in the upper section. 6.7.4 *.msp & emTeX -------------------- If you are using emTeX and you want to include an MSP image to your DVI file you have to add !tex_emtex to your preamble. Furthermore you have to set the resolution of an image via !tex_dpi. The macros for emTeX are generated according to the information of dvidrv.doc of emTeX. In first place UDO tries to read in the header of tiger.msp when reading the command !image tiger A tiger. If UDO doesn't find tiger.msp it will try to find tiger.pcx. An example shows what kind of macro UDO generates for emTeX. `w' and `h' represent the width and height of the image: \begin{figure}[htb] \begin{...} \begin{picture}(,) \put(0,){\special{em:graph tiger.msp}} \end{picture} \end{...} \caption{A tiger} \end{figure} Please note: I use !tex_dpi 300 on my HP DeskJet 510 to display screenshots. 6.7.5 *.pcx & emTeX -------------------- If you are using emTeX and you want to include a Paintbrush PCX to your DVI file you have to add !tex_emtex to your preamble. Furthermore you have to set the resolution of an image via !tex_dpi. The macros for emTeX are generated according to the information of dvidrv.doc of emTeX. In first place UDO tries to read in the header of tiger.msp when reading the command !image tiger A tiger. If UDO doesn't find tiger.msp it will try to find tiger.pcx. An example shows what kind of macro UDO generates for emTeX. `w' and `h' represent the width and height of the image: \begin{figure}[htb] \begin{...} \begin{picture}(,) \put(0,){\special{em:graph tiger.pcx}} \end{picture} \end{...} \caption{A tiger} \end{figure} Note: In first place UDO tries to find an MSP image. If you are using images from Paintbrush PCX you can ignore the warning printed by UDO. 6.7.6 *.gif & HTML ------------------- UDO can generate HTML commands to include a GIF. UDO doesn't check if the GIF is existing! For HTML the second parameter of the !image command will be used as the alternative text. The command !image tiger A tiger will be converted into the following HTML commands:

(Figure 1: A tiger)


If you don't set the title of this image UDO doesn't output an alternative text. The command !image tiger will be converted into this:


6.7.7 *.jpg & HTML ------------------- By default UDO expects that you want to display GIF's (see above). But it's possible to display any other kind of image format, too. To tell UDO which suffix you want to use the next time you use the !image command you can use the command !html_img_suffix. If the upper tiger isn't inside a GIF but inside a JPEG image you can insert the following command right before the !image command: !html_img_suffix jpg If the file is named tiger.jpeg instead of tiger.jpg use the following line: !html_img_suffix jpeg The setting is used for all following images. If you want to display a GIF next time you have to use !html_img_suffix gif before the next !image command is used. 6.7.8 *.bmp & WinHelp ---------------------- UDO can generate commands for Windows Help to display Windows bitmaps (BMP). UDO doesn't check if a BMP is existing! An image can be displayed with or without a subtitle. Windows Help centers the image in the help file. 1. without subtitle: !image tiger 2. with subtitle: !image tiger A tiger UDO will then generate these commands: {\qc \{bmc tiger.bmp\}}\par\pard \par {\qc (Figure 1: A tiger)}\par\pard Please note: 1. UDO won't check if the image file is existing. If it doesn't exists or the filename is wrong the Microsoft Helpcompiler will print an error message. 2. With the switch !win_inline_bitmaps you can tell UDO to use special Windows Help commands to use "hard-coded" images. 6.8 Hypertext commands ======================= 6.8.1 Labels ------------- Using the command !label you can set labels inside the source file. An example: !label example When converting to the hypertext formats Windows Help, HTML, ST-Guide and Pure C Help UDO inserts references inside the text to this label automatically. You can search for these labels inside the search dialog of Windows Help. When you set the upper label you can jump from every position where the word "example" is used to the position where you used the label. Here a list how UDO converts a label for the hypertext formats: HTML: LaTeX: \label{example} Linuxdoc-SGML: a word LaTeX: a word (see \ref{the link}) ST-Guide: @{"a word" link "the link"} WinHelp: {\uldb a word}{\v the_link} Turbo: {a word:the_link} else: a word (see "the link") The following example shows how to insert a link to my contact addresses: If you want to register UDO, please send (!link [me] [Contact addresses]) an email. ... will be displayed this way: If you want to register UDO, please send me (see "Contact addresses") an email. Please note: 1. You may use up to (!MAXLINKS) inside a paragraph. If you will use more links UDO will print an error message. 2. When converting to hypertext formats UDO checks if the link des- tination exists. If it doesn't exits UDO prints an error message. When converting to the other formats UDO doesn't check if the link destination exists! 3. LaTeX only allows it to link to aliases and labels. 6.8.2.2 Internal links with images Especially for Windows Help and HTML there's existing the (!ilink...) ("image link") commands. It is a mixture of the (!img...) and (!link...) command that allows to display "hyperimages". If you click an image you will jump to another part of the current document. UDO: (!ilink [img] [text] [link]) WinHelp: {\uldb \{bmc img.bmp\}}{\v link} HTML: text else: like (!link [text] [link]) Please note: 1. UDO won't check if the images exist. 2. By default UDO uses `.gif' as the suffix for images when converting to HTML. You can use the command !html_img_suffix to change the suffix. 3. You may use up to (!MAXLINKS) inside a paragraph. If you will use more links UDO will print an error message. 6.8.2.3 Internal links to pages Especially for LaTeX there's existing the (!plink...) ("page link") command: UDO: (!plink [link commands] [Links]) LaTeX: link commands (see page \pageref{Links}) else: link commands The following example shows how to insert a page like to the page that contains my contact addresses: If you want to register UDO, please send (!plink [me] [Contact addresses]) an email. ... will be displayed this way: If you want to register UDO, please send me an email. Please note: 1. You can only insert page links to labels and aliases, not to chapters when converting to LaTeX. 2. You may use up to (!MAXLINKS) inside a paragraph. If you will use more links UDO will print an error message. 6.8.2.4 External links With the (!xlink...) ("external link") command you can insert links to (parts of) other documents, net sites or hypertexts. The difference to the upper command: UDO doesn't adjust special chars of the link desti- nation. The tilde isn't a non-breaking space in the link destination, too. UDO: (!xlink [UDO] [*:\udo.hyp]) ST-Guide: @{"UDO" link "*:\udo.hyp"} UDO: (!xlink [Atari] [http://www.atari.com]) HTML: Atari UDO: (!xlink [UDO] [Titel@d:/winhelp/udo.hlp]) WinHelp: {\uldb UDO}{\v Titel@d:/winhelp/udo.hlp} else: UDO (or Atari) Please note: 1. You have to use existing topic names for Windows Help. A topic name must contain only numbers and characters form the alphabet. All other characters will be converted by UDO. 2. You should use `*:\' at the beginning of an external link for the ST-Guide to tell it to look for the hypertext in all directories you defined with PATHS in your ST-GUIDE.INF. 3. Using the switch called !no_xlinks [...] you can suppress the conversion of external links. This is useful if you wrote a source file especially for HTML and you want to make a version for Windows Help or ST-Guide, where the external file wouldn't make no sense. 6.9 Miscellaneous ================== 6.9.1 Macros ------------- Macros are userdefined placeholders that you can use for different purposes. When using the !macro command you tell UDO the name of the macro in first place. The name of the macro is followed by its contents which may be empty, too. Let me show you some examples: !macro HTML Hypertext Markup Language !macro UDO (!B)U(!b)niversal (!B)Do(!b)cument !macro DOSG (!T)UDO6GDOS.ZIP(!t) !ifdest [html] !macro PICPATH gif/ !else !macro PICPATH img/ !endif [...] The (!HTML) ... The (!UDO) Format ... The archive named (!DOSG) ... !image (!PICPATH)/tiger Macros can help you to save time when typing often used long words. Furthermore macros can help you to change the contents of your file by simply changing the contents for macros (e.g. if your program name changed and you use a macro for the name of your program). Another example is the usage of standardized text (e.g. a standard disclaimer) where you use macros instead of the name of the program etc. These standardized texts can be included with !include. In the following example a disclaimer is included and the name of the program is defined by a macro: [doku.u] !macro PRG Windows95 [disclaim.u] (!PRG) is provided ""as is"" without a warranty of any kind. Use it on your own risk. Since UDO Release 6 you can call macros with parameters. You can set the position of the parameters in the !macro command by inserting `(!1)', `(!2)' till `(!9)'. To call a macro with parameters you have to write brackets (`[...]') around them. The following small example shows how to use a macro for text that shall be printed in bold-italic style: !macro BI (!B)(!I)(!1)(!i)(!b) ... This text is printed (!BI [bold and italic]). The "(!1)" in the macro line will be replaced by the words "bold and italic". Please note: 1. When naming the macros you should be cautious not to use pre- defined UDO command names like "B" or "nl". If you don't you will get problems with bold text ((!B)) or the newline command ((!nl)). 2. You shouldn't use too many macros because every additional macro slows down the conversion of the source file. The maximum number of macro is 128. 6.9.2 Definitions ------------------ Like macros definitions are user-defined placeholders. You can use them to insert special commands inside the text especially for the destination format. The syntax is !define . In contrast to macros will not be converted in a special way. No special characters are translated inside . In this example I will demonstrate how to print headlines with HTML: !ifdest [html] !define H1

!define h1

!else !define H1 !define h1 !endif [...] (!H1)A headline(!h1) As you can see you can use definitions to insert special commands that aren't supported by UDO. UDO Release 4 offered a lot of special commands for LaTeX that you now have to simulate with the !define command: !ifdest [tex] !define ff "ff !define nolb3 \nolinebreak[3] !define lb2 \linebreak[2] !else !define ff ff !define nolb3 !define lb2 !endif [...] Tell (!LaTeX) a good place (!lb2) for breaking lines. You can use definitions with parameters, too. Definitions with parameters are used the same way you can use macros with parameters. Definitions with parameters are a great help to expand UDO's support of a destination format. You declare definitions like in the upper example. You can tell UDO the positions of the parameters by adding `(!1)', `(!2)' till `(!9)'. When you call a definition you have to write brackets (`[...]') around the parameters. In the upper example I have shown you how to make a heading for HTML. When using parameters it may look like the following example: !ifdest [html] !define head

(!1)

!else !define head (!1) !endif [...] (!head [A headline]) As you can see in this example you can write format depending commands UDO doesn't support already. The upper LaTeX example can be defined nicer, too. If you use parameters you can provide all available LaTeX commands in one definition: !ifdest [tex] !define lb \linebreak[(!1)] !else !define lb (!2) !endif [...] Tell (!LaTeX) a good place (!lb [2]) for breaking lines. In this example only one parameter is used but the non-LaTeX definition contains a second parameter. You may ask yourself why it has to be like this. Well, if you call the definition with only one parameter the second parameter is empty. When expanding the non-LaTeX definition UDO will replace the definition placeholder by empty space (because there is no second parameter, you understand?). Unfortunately you have to use this work-around when using definition with placeholders. Please note: 1. Characters of text of the !define command won't be converted. 2. Characters of the parameters you pass to the definition will be converted. 3. UDO supports the !heading command for displaying headlines. The upper HTML example is only used for demonstration. 4. When naming the definitions you should be cautious not to use pre-defined UDO command names like "B" or "nl". If you don't you will get problems with bold text ((!B)) or the newline command ((!nl)). 5. You shouldn't use too many definitions because every additional definition slows down the conversion of the source file. The maximum number of definitions is 128. 6.9.3 Indices -------------- To add entries for the index you can use the !index command or the (!idx ...) placeholder. You can and should use these commands as often as possible. To add an entry with the !index command use it this way: !index Index entry The entry appears inside the index of LaTeX, inside the index of a Texinfo file that was printed with TeX, inside the index of an ST- Guide hypertext, inside the search dialog of Windows Help and inside the index of an RTF file. To insert a multi-index you can separate the index entries with a double exclamation mark. You can use up to three indices in one line. You should use multi-indices when it's obvious that a potential reader looks for an entry in different ways. If you think that a reader might look for "Index entry" or "Entry, Index" you should use the following index commands: !index Index entries !index Entry !! Index If you use the placeholder (!idx ...) you can use up to four parameters. The following examples show how the commands are converted for LaTeX, Windows Help and RTF: UDO: an (!idx [entry]) LaTeX: an entry\index{entry} Win: an {K{\footnote K entry}}entry else: an entry UDO: a (!idx [word] [entry]) LaTeX: a Wort\index{entry} Win: a {K{\footnote K entry}}word else: a Wort UDO: a (!idx [word] [entry] [subentry]) LaTeX: a word\index{entry!subentry} Win: a {K{\footnote K entry, subentry}}word else: a word UDO: a (!idx [word] [entry] [subentry] [subsubentry]) LaTeX: a word\index{entry!subentry!subsubentry} Win: a {K{\footnote K entry, subentry, Subsubentry}}word else: a word Please note: 1. The conversion of these index commands can be suppressed with the switch !no_index inside the preamble. 2. Chapter names, labels and aliases aren't added to the index in no destination format. But you can automatize this with the following switches: !use_nodes_inside_index, !use_label_inside_index and !use_alias_inside_index. 3. If a chapter contains the command !ignore_index the chapter name won't be added to the index even if you use the switch !use_nodes_inside_index inside the preamble of your source file. 4. If you convert to LaTeX and you use !index commands inside your source file UDO will add the commands that are necessary for "Makeindex" automatically. Special characters of an index entry are converted especially for "Makeindex". 5. You have to use the parameters inside brackets. If you want to use a bracket inside a parameter you have to insert a `!'. If you don't UDO will think that the placeholder ended. An example: wrong: (!idx [Copyright (c) 1995] ) right: (!idx [Copyright (c!) 1995] ) 6.9.4 Special commands ----------------------- UDO offers you two commands and an environment for every destination format that you can use to insert special commands for this format. So you are able to insert small passages or huge blocks written in the destination format (like special tables for LaTeX or HTML). You have to use abbreviations of the destination formates if you want to use these special commands: asc ASCII aqv Apple QuickView htag HP Helptag SGML html HTML info Texinfo ldoc Linuxdoc-SGML lyx LyX man Manualpage pch Pure C Help pdf PDF rtf RTF stg ST-Guide tex LaTeX tvh Turbo Vision Help win Windows Help For every destination format UDO offers a command to insert a line with commands for the current destination format, and a command to insert a line for all different formats. The commands are built by a `!' and the abbreviations or `!=' plus the abbreviation. The next example shows how to insert a line that will only be printed for the ASCII format: !asc This line appears only in ASCII. The next example shows how to insert a line that appears in all formats except ASCII: !=asc This line doesn't appear in ASCII. The contents of the line will be printed without the command and without converting the text of the line. These commands split up text into different paragraphs like all the other UDO commands. So these commands aren't useful to insert a line into a paragraph! You can use these commands to insert special commands like parts of the preamble for LaTeX: !tex \documentstyle[11pt,makeidx]{article} !tex \makeindex [...] !tex \printindex The raw environment ------------------- But it happens that you want to insert large passages only for one format with special commands. You could add one of the upper commands at the beginning of each line, sure. But to make it easier for you to insert these passages UDO has a special environment for this case: the raw environment. Together with the possibility to check the current destination format you can e.g. insert complex tables for LaTeX or forms for HTML with the raw environment. The following example shows how to enter HTML forms to your source code: !ifdest [html] !begin_raw 
     
    Name:
!end_raw !else The HTML version will display a form here. !endif To say it once more: Text that is part of a raw environment is printed "as is". That means that it's not converted and not indented. If you will insert the upper form source code into a verbatim environment you will see the source code in an HTML browser. But if you insert it inside a raw environment you will see the form! 6.9.5 Split documents ---------------------- UDO offers you the commands !include, !vinclude and !rinclude. With these commands you are enabled to split up a document into many files that are included by a main file. Furthermore you can use these commands to include an often used passage that you have to type only once. This documentation uses this commands intensively. The file udo.u doesn't contain any text and just includes other files. So I have the possibility to find some passages more fast if I have to change the documentation. You can use !include wherever you want. So you can define macros, definitions or syllabification patterns in external files that can be used by other files, too. For displaying the preformatted contents of a file you can use the !vinclude command ("verbatim include"). You can use this command e.g. for displaying source files or header files. If you want to included special commands for a destination format like difficult tables for LaTeX or HTML you can use the !rinclude command ("raw include"). Possible examples of use: 1. When writing large source files you can edit a separate file for each chapter that are included by a main file with !include. Thus you can restructure your text by simply moving one line of the main file. 2. If you split up your text into several file that are included by a main file you can speed up looking for errors because you can simply switch off some parts of the text by commenting out one line of the main file. 3. Together with macros you can write standardized texts that you can use for many projects. E.g. you can edit a standard disclaimer where the name of the software is replaced by macros that are defined by the main file. 4. A documentation can be written by different persons. Each author can test his own file with UDO. If everybody has finished his work all files will be included by a main file. 5. With !vinclude and !tabwidth you can add source code to your documentation. This is great for a documentation of a source code or a library. ====================================================================== Chapter 7 Tips & tricks ====================================================================== In this chapter I will tell you some tips for your writing UDO source files. Furthermore I will show you some tricks. Maybe these tricks can help you solving some of your problems. I'm going to add additional tips in the near future. Watch out for new versions of this documentation or for new UDO Releases. 7.1 Seven rules for writing UDO source files ============================================= Before starting to write UDO source files you should take a look at these rules and learn them by heart: 1. Arrange your documentation clearly! 2. Speak directly to the reader. Use "You can..." instead of "It's possible to...". 3. Use text styles sparingly and homogeneously. Don't use italic, bold and underlined text too often. But if you use different text styles use them homogeneously. This documenta- tions prints all UDO command in italics, all filenames are printed with a mono-spaced font. 4. Make it brief as possible. Don't write novels, come straight to the point. If you don't the reader may get bored while reading your manual. I have to admit that I'm not able to do this in some cases. ;-) 5. Use short chapter names. If you use short chapter names the reader will find the chapter more quickly after having read the table of contents. Furthermore you can help UDO to insert hypertext links more quickly. 6. Avoid to use the same chapter name more than once. If you use the same chapter name more than once UDO and the hypertext compilers get confused. And you will confuse the reader, too. 7. Use macros and definitions sparingly. UDO has to look for macros and definitions twice in every line of your source file. Any additional macro or definitions slows down the conversion. 7.2 General tips & tricks ========================== 7.2.1 Split large documentations --------------------------------- If you write a documentation that is 30 KB or larger you should split up it into different parts that you can merge with !include. By splitting up the documentation you are e.g. enabled to restructure it by simply moving one line of your main source file. If your docu- mentation is part of one file you have to move blocks of text to restructure it. Another advantage is that you can find specific chapters more quickly if you write them to files that you name like this chapter. Furthermore you can test or convert only some parts of the documenta- tion. My be you have a documentation with five chapters. Write a preamble file, a main file and five files that contain the chapters: [main.u] !include header.ui !begin_document !maketitle !tableofcontents !include chapter1.ui !include chapter2.ui !include chapter3.ui !include chapter4.ui !include chapter5.ui !end_document [header.ui] !title ... !program ... !author ... [chapter1.ui] !node Chapter 1 ... [chapter2.ui] !node Chapter 2 ... [etc] If you now want to convert a single chapter you simply edit another main file: [ch5test.u] !include header.ui !begin_document !maketitle !tableofcontents !include chapter5.ui !end_document If you use this method you will be able to find errors in a large documentation more quickly. Just take a look at the source files of the UDO documentation if you want to know how to split up a large documentation. You can believe me that it would be hard work if all the text would be part of a single text file. 7.2.2 Use standardized source files ------------------------------------ There are some authors that write every few weeks a new program or a new hypertext. And in every documentation you can read a disclaimer or a copyright chapter. Wouldn't it be easier to use the same text all the time? No problem, just use macros. The following example shows how to use a standardized copyright text. May be you have a written a program that contains this copyright note: ""Hello, World!"" Version 8.15 (!nl) Copyright (!copyright) 1996 by C. Rookie Your next program contains a similar text, only the name of the program and the version number differ. Wouldn't it be better to use a standardized text any time you write the documentation of a new software? ""(!PrgName)"" Version (!PrgVersion) (!nl) Copyright (!copyright) (!PrgYear) by C. Rookie Here the name, the version number and the years will be replaced by the contents of macros "PrgName", "PrgVersion" and "PrgYear". If you write the upper text to a sinlge file you can use it for many documen- tations where only the macros have to be defined. !macro PrgName Hello, World! !macro PrgVersion 8.15 !macro PrgYear 1996 ... !begin_document ... !include copyleft.ui It's true that this is only a small example. But you can make more complex files if you want to. 7.2.3 Write your own commands ------------------------------ UDO doesn't support every command of the destination formats. If you need a special command you can add it by using definitions with parameters. You only need some knowledge about the destination format. The following example shows how to write commands for changing the font size for LaTeX, HTML, Windows Help and RTF: !code_iso !program Changing the font size !author Dirk Hagedorn !date August 19th 1996 !ifdest [tex] !define tiny {\tiny{(!1)}} !define large {\large{(!1)}} !define Large {\Large{(!1)}} !define LARGE {\LARGE{(!1)}} !define huge {\huge{(!1)}} !define Huge {\Huge{(!1)}} !endif !ifdest [win,rtf] !define tiny {\fs14 (!1)} !define large {\fs28 (!1)} !define Large {\fs36 (!1)} !define LARGE {\fs44 (!1)} !define huge {\fs50 (!1)} !define Huge {\fs60 (!1)} !endif !ifndest [tex,win,rtf] !macro tiny (!2) !macro large (!2) !macro Large (!2) !macro LARGE (!2) !macro huge (!2) !macro Huge (!2) !endif !begin_document !maketitle !tableofcontents !node Test (!tiny [tiny]), normal, (!large [large]), (!Large [Large]), (!LARGE [LARGE]), (!huge [huge]) und (!Huge [Huge]). !end_document 7.3 Tips & tricks according to LaTeX ===================================== 7.3.1 A user-defined LaTeX preamble ------------------------------------ In contrast to the previous UDO version UDO Release 6 will save a LaTeX preamble automatically for LaTeX 2.09 or LaTeX2e. If you don't like the automatically generated preambles you tell UDO not to save them by using the switch !no_preamble [tex] inside the preamble of your UDO source file. In this case you can enter the special LaTeX commands at the beginning of the UDO source file with !tex or a raw environment. The following example shows how you can do this: !code_iso !no_preamble [tex] # Uncomment the following line for LaTeX 2.09 # !tex \documentstyle[12pt]{article} # Uncomment the following lines for LaTeX2e !tex_2e !tex \documentclass[12pt,a4paper] !tex \usepackage{a4} !begin_document !node Example This example uses a userdefined (!LaTeX) preamble. !end_document 7.4 Tips & tricks according to ST-Guide ======================================== 7.4.1 A user-defined title page for ST-Guide --------------------------------------------- If you don't like the layout of the title page UDO will make with !maketitle you can make your own title page with some commands: The following example shows how to make your own title page but only for the ST-Guide. It's used a "hidden" node that contains the word "Contents" at the end. The ST-Guide will insert a link to the table of contents due to this word. !program Title pages with UDO !begin_document !ifndest [stg] !maketitle !else !node* Title !begin_center The hypertext to ""Hello, World!"" (!nl) Version 8.4 written by Ford Prefect !end_center !smallskip !begin_center Contents !end_center !endif !tableofcontents !node The first chapter This is the first chapter !node Bye bye Stop it, now! !end_document 7.4.2 Don't use justified text ------------------------------- "Why that?" you might ask. Well, Martin Osieka has written a program called Hyperion for the Apple Macintosh that can display ST-Guide hypertexts. In contrast to ST-Guide Hyperion can display hypertexts with proportional fonts but only if you don't use justified text. Thus you should don't use the justification if you want that Macintosh users shall also read your hypertext without any problems. If you have written a system specific hypertext that is only interesting for Atari users you can use justification without any doubts. 7.5 Tips & tricks concerning Windows Help ========================================== 7.5.1 Write the source files with a Windows editor --------------------------------------------------- You can speed up the conversion if you write the source files with a Windows editor. In this case UDO doesn't have to convert the charac- ters from the IBM PC character set into the Windows ANSI character set. If you write source file with a Windows Editor you have to insert the switch !code_iso inside the preamble of your source file. If you forget to do this UDO will think that the source file was written with the IBM PC character set. Tip: I recommend to use the "Programmer's File Editor" (PFE) written by Alan Phillips, a really great freeware editor that is available both for Windows 3.11 and Windows95/NT. 7.5.2 Compress the Windows Help files -------------------------------------- Using the switch !win_medium_compression or !win_high_compression you can tell the Microsoft Helpcompiler to compress the final Windows Help file up to 50%. The Microsoft Helpcompiler will need a little bit more time to convert the RTF source file if you use the upper switches. ====================================================================== Appendix A Frequently asked questions ====================================================================== This chapter shall help you to solve smaller problems. You will find some answers to internal questions about UDO, too. In first place general questions are answered, in second place the format specific questions will be answered. A.1 General questions ====================== Why is UDO names `UDO'? When I began programming UDO I had no better idea than naming it "UDO", the abbreviation for "Universal DOcument". By the way: The author's prename isn't Udo, he's called Dirk! How to I pronounce `UDO'? `UDO' is pronounced like the prename Udo: `Ooh-do'. Pronounce the `U' like the `u' in `butcher', the `do' like the `do' in `document'. Please don't pronounce it like `You do'. How can I get the current versions? You can download the current version from a BBS and via FTP or from the World Wide Web. The current versions are always available in the BBS called "Maus MK2 Iserlohn-Kalthof" (+49 2371 944925) in the "Gruppenprogrammteil UDO.Pub". After the login press `P' for `Programmteil', press `G' for `Gruppenprogrammteil' and enter `UDO.Pub'. You can list all archives by pressing `A' (`AusfÏhrliche Liste') and `L' (output list). Remember the number of the archive and start the download by pressing `D' and entering the number of the archives. To download the current version from the World Wide Web open the URL http://members.aol.com/UDODH/index.htm. Here you will find links to the UDO archives. To download them via FTP open a connection to members.aol.com/UDODH/ (not ftp.members.aol.com!), members.aol.com/UDOENG/ or members.aol.com/UDOADD/. If you don't own a modem and you don't have access to the Internet you can get the current version by simply sending me a formatted floppy disk besides a readdressed envelope and 2 DM for stamps. Please tell me which operating system you use. The names of the archives are constructed in the following way: udorlyyy.sss ||| || | ||| |+--+--- .zip: ZIP archive ||| | .tgz: tar gzip archive ||| | ||+-+------- beo: version for BeOS || hp4: version for HP-UX, 300/400 || hp8: version for HP-UX, 700/800 || lin: version for Linux || mac: version for MacOS || nex: version for NeXTStep || sin: version for SINIX || sun: version for SunOS || tos: version for Atari ST and clones || dos: version for DOS, OS/2 and Windows || man: source files of this manual || |+---------- g: version with German manual | e: version with English manual | +----------- Release number: 6 for UDO Rel. 6 The archive containing the English version for MS-DOS is called udo6edos.zip, the archive containing the English source files of this manual is called udo6eman.zip. The Unix version may have longer names like udo6_ger_linux.tar.gz or udo6_eng_hp-ux-34.tar.Z. Will there be versions for other operating systems? At the moment UDO is available for the following operating systems: ü Atari TOS ü BeOS ü DOS, OS/2, Windows ü HP-UX 9.x for 300/400 and 700/800 models ü Linux i86 ü MacOS ü NeXTStep ü SINIX UDO was completely written in highly portable C. The source code doesn't call any system specific functions. Due to this fact UDO could be ported to any operating system a C compiler is existing for. Can UDO generate formats from other systems? Sure. E.g. you can run UDO on a Windows PC and save Linuxdoc-SGML files. You can run UDO on a Linux PC and save Windows Help files. No problem. UDO has the same functions on any operating systems it's available for. Maybe you have only to convert the file with GNU-Recode later if the charsets are not the same. Can I write my source files "here" and translate them "there"? Yes, you can e.g. write your source files on a Windows PC and convert them on a BeBox or Apple Macintosh. UDO knows the charsets of all operating system it's available for. You have only to say UDO which charset was used for writing the source files by using the commands like !code_iso or !code_mac. Do you want to support other destination formats in the future? Yes, I want to support the following formats if I will get any information about them and if I'm allowed to generate them without paying any licences to anybody: ü Apple Guide ü HP HelpTag SGML ü OS/2-Help ü Portable Document Format `PDF', Adobe Acrobat Reader ü Postscript May the UDO syntax change in the future? UDO is that kind of software that is improved day by day. New commands will appear in the future, that's for sure. In some cases it will be necessary to change the syntax of some commands. But I will tell you about these changes. Just take a look at the "History" to get to know about the changes in the past. How does UDO work? UDO reads the source file(s) in two passes. In the first pass UDO reads in the switches, macros, definitions and the chapter titles that are needed for referencing. In the second pass UDO will convert and layout the text. UDO will save all lines in an internal buffer until it reads an empty line or an UDO command. A command or an empty line tells UDO to layout the last paragraph and to go on reading the source file. How does UDO reference other parts of the document? UDO inserts links in hypertext formats (except for the ST-Guide) automatically to other parts of the documentation. UDO references chapter titles, labels and aliases. Using the switch !autoref [off] you can tell UDO not to insert any references until you use the switch !autoref [on]. How can I link to parts of the current page? Because UDO doesn't insert links to labels of the same page you have to insert a explicit link to this label by using the (!link [ ] placeholder. An example: !node Test !label Test top [...] (!link [Back to top of page] [Test top]) How can I display images in the table of contents? You have to make your own table of contents, that means you have to leave the !tableofcontents command. An example: !begin_document !maketitle !node Contents !image foo !toc [all] !node First chapter A.2 Questions concerning ASCII =============================== Do you plan to split up ASCII manuals into separate files? Only one (unregistered) user has wished yet that UDO should output chapters etc. to separate files as it does for HTML. Because no one else has asked me to do this yet I haven't imple- mented this feature. But if there's a need for this feature I will implement it. The functions still exist and have only to be adapted for ASCII. Some lines are larger than 70 characters, why? These are the lines that contain bold, italic or underlined words. These text styles are generated with the characters *, / and _ like in Usenet. Because of the existence of some print tools (e.g. IdeaList for Atari ST) and newsreaders know these text styles UDO doesn't count these special characters. If you want to suppress the output of these characters you can use the switch !no_effects [asc] inside the preamble. 8bit characters are wrong when viewing an ASCII file with Windows!? UDO saves ASCII files that use the system charset of your operating system. UDO is a DOS software, not a Windows software. So it will use the IBM-PC charset and not the Windows ANSI charset. Just view the ASCII files with the System font or Terminal font and you will believe me that the 8bit characters aren't wrong. How can I change the paragraph width? The paragraph width can be changed with the !parwidth command. A.3 Questions concerning HTML ============================== How can I tell UDO not make files for each chapter? In contrast to the other formats UDO saves a separate HTML file for each chapter by default. UDO names these files by using the chapter numbers. The title page and the table of contents will be saved in the file you passed in the command line. Using the switches !html_merge_nodes, !html_merge_subnodes, !html_merge_subsubnodes or !html_merge_subsubsubnodes you can tell UDO not to save a file for each chapter. If you use !html_merge_nodes inside the preamble UDO will save only one HTML file that contains the whole text. You should use this option only for small source files. If you use !html_merge_subnodes UDO will save separate files only for chapters. All sections, subsections and paragraphs of a chapter will be saved inside this file, too. If you use !html_merge_subsubnodes UDO will save separate files for chapters and sections. The subsections and paragraphs of a section will be saved in the file that contains the text of the upper section. Finally if you use !html_merge_subsubsubnodes the paragraphs of a subsection will be saved in the file that contains the text of the subsection. UDO will save separate files for chapters, sections and subsections. I don't like the names of the HTML files! Using the command !html_name inside a chapter, section, subsection or paragraph you can tell UDO which filename it shall use instead of using a filename like "01020304.html". How can I suppress these ugly headlines? UDO will print on every HTML page a headline that contains the title of the documentation and hypertext links to the previous, next and upper page. UDO uses GIF's for these links that are saved by UDO automatically. The filenames of these GIF's are udo_lf.gif, udo_rg.gif and udo_up.gif. Using the switch !no_headlines [html] inside the preamble you can tell UDO not to generate these headlines. How can I easily make my own headlines or bottomlines? If you want to make your own headlines or bottomlines you can use macros at the beginning of each chapter. The following example shows how I added bottomlines to my WWW pages. These pages contain links to the chapters that contain my address, the de- scriptions of my software and links to other web sites. Main file: !ifdest [html] !define HR
!macro HEAD [ Software | Contact addresses | Links ] (!HR) !macro FOOT (!I)Dirk Hagedorn - last updated on (!short_today)(!i) !else !define HR !macro HEAD !macro FOOT software.ui: !node Software !html_name software (!HEAD) [...] (!FOOT) If you convert the source file to HTML UDO expands the macros that contain the text of the headlines and bottomlines. Because UDO insert links automatically you can jump to the other pages by clicking the entries of the bottomline. If you don't convert to HTML empty macros are used so that nothing will appear when using (!HEAD) or (!FOOT). Sometimes a table has a frame, sometimes it hasn't!? Unfortunately HTML only allows to use tables with or without frames. You cannot use table lines where you want to. To print a table with a frame you have to add !hline to the line that contains !begin_table. If you don't want a frame don't use !hline. That's all. Which suffixes does UDO use for HTML files? By default UDO uses the suffix of the --outfile you used in the command line: -o index.htm .htm -o index.html .html -o INDEX.HTML .HTML If you use the option -o ! UDO uses `.htm' on operating systems with 8+3-filenames and `.html' on operating systems with long filenames. The filenames of the URL's are wrong!? If you use UDO on an operating system that doesn't support long filenames but you have used `--outfile index.html' and you copy the saved `.htm' files to a web server, remember this: 1. UDO will try to save `index.html' but TOS and DOS will name it `index.htm'. 2. UDO will use for all hypertext links the suffix `.html' because of the suffix of the `outfile'. If you use a HTML browser for TOS or DOS this browser will open `index.html' without any problems even if there's only a file named `index.htm'. 3. When copying the files to a web server you have to change the suffixes from `.htm' to `.html'. If you will forget this all links will be wrong. A.4 Questions concerning manpages ================================== The Manualpage is an ASCII format where text styles are made by inserting backspace sequences. It's used for short software descrip- tions for Unix systems. For longer descriptions you should use the GNU Texinfo format. How can I set the page length for manpages? You can set the lines each page of a manpage should have with the command !man_lpp ("lpp" means "lines per page"). How can I set the program type for manpages? Use the switch !man_type X where "X" is displayed inside brackets in the headlines of the manpage. Why doesn't UDO print a table of contents? It's very unusual to use a table of contents in a manpage. For short program description - you only should use manpages for - tables of contents don't make sense, too. A.5 Questions concerning LaTeX =============================== How does UDO create the LaTeX preamble? UDO knows which language and which document style you use. Furthermore UDO knows if you are using indices or not. So UDO knows enough to create the LaTeX preamble on its own. How can I make files for LaTeX2e? By default UDO saves files for LaTeX 2.09. If you use the switch !tex_2e inside the preamble UDO will save a preamble and other special commands for LaTeX2e. I want to use a userdefined preamble!? Use the switch !no_preamble [tex] inside the preamble of your UDO source file and insert the userdefined LaTeX preamble into a raw environment at the beginning of your UDO source file. How can I use LaTeX formulas inside the text? Use a raw environment for complete paragraphs or definitions for floating text. An example: !ifdest [tex] !define ab2 $(a+b)^2 = a^2 + 2ab + b^2$ !else !macro ab2 (a + b)^2 = a^2 + 2ab + b^2 !endif ... The first binomial theorem: (!ab2) How does UDO translate special chars in indices? Special characters are translated especially for makeindex. When I use brackets inside indices a LaTeX error appears!? You have to use a `}' for any `}' inside an index entry and vice versa. Otherwise LaTeX will print an error message. A.6 Questions concerning Linuxdoc-SGML ======================================= In March 1996 I found an article in the German Unix magazine "iX" about Linuxdoc-SGML. It took two hours to download the Linuxdoc-SGML archive and to implement this format into UDO. Unfortunately I didn't own a Linux computer and so I wasn't able to test UDO's output. Linuxdoc-SGML is a multiformat converter like UDO. With Linuxdoc-SGML you can convert SGML files into LaTeX, RTF, HTML, Texinfo and manpages. But it's not a lie if I say that UDO is more powerful than Linuxdoc-SGML 1.5. The xlist environment is handled like a description environment!? Linuxdoc-SGML doesn't offer an environment like UDO's xlist envi- ronment. So UDO is forced to handle it like a description envi- ronment. Linuxdoc-SGML doesn't know Å, why? Add the following line to /usr/lib/linuxdoc-sgml/rep/html/ general: A.7 Questions concerning Pure C Help ===================================== The Pure C Help format is only useful for the Pure C compiler on Atari ST for displaying online library descriptions. The format isn't used for any other purposes neither on this nor on other computers. How does UDO print the title page and the table of contents? UDO prints a single page that contains both the title page and the table of contents. Because this page can get very long you should use the switch !use_short_toc [pch]. How can I suppress the headlines? UDO prints a headline on each page automatically. Headlines contain the name of the current chapter and the title of the source file. By clicking the title you can jump to the title page or the table of contents. Using the switch !no_headlines [pch] you can suppress the output of these headlines. How can I suppress the bottomlines? UDO prints a bottomline on each page automatically that contain links to the previous page, next page and upper page. Thus the reader of the online manual is enabled to jump directly to other pages without returning to the table of contents. Using the switch !no_bottomlines [pch] you can suppress the output of these bottomlines. What can I do with the file with the suffix .cmd? UDO saves a command file for the Pure C Help compiler HC.TTP. You have to call the HC by passing the name of this command file to get a compiled help file. UDO always overwrites this file. You have to switch in write protection if you want to protect your own changes to this file. How do I build a help file for Pure C? UDO saves two file when converting the source fie foo.u: foo.scr and foo.cmd. To get a Pure C Help file you have to call HC.TTP by passing the command file foo.cmd: $ e:\purec\hc.ttp foo.cmd Using GEM just drag foo.cmd onto HC.TTP to start the conversion. How can I install this help file? Pure C can display on user defined help file. This file has to be named USR.HLP and it has to be placed inside the Pure C directory. To install your help file backup the original USR.HLP, rename your help file to USR.HLP and copy it to the Pure C directory. A.8 Questions concerning the Rich Text Format ============================================== The Rich Text Format (RTF) is used for the system wide exchange of text files. This format has a strict definition. New commands can be added every time. If a RTF software reads in an unknown command it has to ignore it. Unfortunately not all the existing software ignore unknown RTF commands, some are interpreting some senseless stuff. Microsoft Word doesn't interpret the RTF correctly in all cases, even if Microsoft has developed the Rich Text Format. It's not wrong if I say that RTF is the most misinterpreted format ever known. Why doesn't UDO print a table of contents? I think you are the reader of your documentation wants to print it out with a text processor. And it's for sure that you want the correct page numbers inside the table of contents. But UDO cannot know on which page a chapter will be printed. Thus it doesn't print a table of contents when converting to RTF. OK, it wouldn't be a problem to print it but I think you don't want a table of contents without page numbers. Why doesn't UDO include the image data into the RTF file? Because I don't know until today how image data is converted into RTF data. If you can tell me how this is done, please tell it to me. The output of my text processor is horrible, why? Bad luck. You own a text processor that cannot import RTF correctly. UDO strictly pays attention to the RTF definition. If it's possible for you to contact the authors of your text processor send them your RTF file. By the way: I also tried to get contact to authors of text processors but only one author (Christian Nieber, R.O.M. logicware, Papyrus) answered my emails. Can you imagine that? 8-bit characters aren't imported correctly!? UDO saves RTF files that use the Windows ANSI character set. Every text processor should be able to import RTF files that use the IBM-PC character set, the Macintosh character set and the Windows ANSI character set. If some 8-bit characters are displayed incorrectly it's a problem of your text processor and not a bug of UDO. Quotes aren't imported correctly, why? UDO uses the RTF commands \lquote, \rquote, \rdblquote and \ldblquote for displaying the typographical quotes and apostro- phes. Your text processor has to know these common RTF commands. If it doesn't want to import these RTF commands or the quotes and apostrophes are displayed incorrectly you can tell UDO not to use these RTF commands by inserting the switch !no_quotes [rtf] inside the preamble of the UDO source file. My text processor cannot import tables. What can I do? Use the switch !rtf_ascii_tables inside the preamble of your UDO source file to tell UDO that it shall print tables without RTF commands like in the ASCII format. StarWriter 3.0 prints an RTF error!? It seems to be that StarWriter 3.0 doesn't know all RTF commands and furthermore it faults correct RTF commands. Please contact Star Division. Indices aren't imported into StarWriter!? StarWriter 3.0 ignores the RTF command `\xe' which is used for indices. Lotus WordPro places chapter numbers outside the text frame!? I'm sorry but I have no idea why it does this. Other text processors display the chapter numbers correctly. Lotus WordPro doesn't display tables correctly!? I don't know why Lotus WordPro doesn't recognize the ending of a table. The table itself will be displayed incorrectly, too. Please use the switch !rtf_ascii_tables inside the preamble of your UDO source file. WordPad doesn't display tables, why? Because WordPad cannot display tables. Use the switch !rtf_ascii_tables inside the preamble of your UDO source file. A.9 Questions concerning ST-Guide ================================== Images aren't displayed centred? Get the current ST-Guide version. Since Release 15 the ST-Guide can center images itself. How does UDO create the title page and the table of contents? The title page and the table of contents are displayed inside a special node. The title page node is named "Title". The node that contains the table of contents is named "Main". To let the ST-Guide display the first page of the hypertext (this will be the title page in most cases) just pass the name of the hypertext. To let the ST-Guide display the table of contents pass the node name "Main". How you can call the ST-Guide from programs you can read in the HCP hypertext. How can I suppress the headlines? UDO prints a headline in every page by default. The headline contains the current node name and the title of the hypertext. The headline will be displayed underlined. Using the switch !no_headlines [stg] inside the preamble you tell UDO not to create these headlines. How does UDO insert hypertext links? UDO just insert hypertext links when you use (!link ...) and (!xlink ...). All the other hypertext links will be inserted by the HCP. How does UDO convert labels? The UDO command !label will be replaced by the HCP command "@symbol ari". You have to check yourself if there's a node or a label existing with the same name. How can I make popup nodes? Using the !pnode and the familiar commands you can tell the ST- Guide to display the contents of the node inside a dialog box instead of a window. But you have to remember that text inside a popup node may have up to 12 lines of text with 60 characters per line only. Furthermore no images and links are allowed inside a popup node. UDO breaks line after 60 characters but it doesn't print an error message if you use more than 12 lines, images or links inside a popup node. There's always an empty line at the end of a popup node, why? UDO reads in the source file line by line. If an empty line appears UDO will print the last paragraph and an empty line for separation. UDO does the same when printing the text of a popup node. The problem cannot be solved, I'm sorry. Some cells of my table are too wide, why? The ST-Guide has a built-in italic correction which is active in tables, too. Unfortunately the ST-Guide adds a blank when it reads an italic-off command. This problem can only be solved by Holger Weets, the author of ST-Guide. Thus you shouldn't use italic text inside tables when converting to ST-Guide until Holger doesn't offer a command for disabling the italic correction. The HCP prints the error message "please add...", why? If the HCP prints the error message "please add a @subject- command to this text" at the end of converting the STG file you have forgotten to insert a line like the following one at the beginning of your UDO source file: !stg @subject "Documentation/Utilities" A.10 Questions concerning Texinfo ================================== GNU Texinfo is used on many Unix systems to offer the user an online hypertext manual and a printed documentation that can be made with `Makeinfo' or plain TeX. Online manuals can be displayed with `Info'. On systems with 8+3-filenames UDO saves files with the suffix .tex. If the operating systems supports long filenames UDO uses the suffix .texi instead. Why does UDO change the chapter names? Makeinfo and/or Info get problems if a chapter names contains brackets, commas or colons. UDO is forced to delete these charac- ters so that you will be able to convert the output with Makeinfo without any problems. If a chapter name contains only forbidden characters UDO encodes them. You will only see the changed chapter names inside the Info headlines and Info menus. If you convert the Texinfo file with TeX you will get your original chapter names. Why doesn't Texinfo display the environments in "compressed" form? Using Texinfo it's impossible to smaller the paragraph separa- tion. Thus the parameter !short is useless when converting to Texinfo. A.11 Questions concerning Turbo Vision Help ============================================ This format is used to make online manuals for DOS programs that are compiled with Borland's Turbo Vision library. UDO's output has to be converted with TVHC.EXE. The source code of TVHC.EXE is available and you have to change some parts because it contains some bugs. If you aren't an author that programs software that uses the Turbo Vision library you shouldn't use this format. TVHC prints the error message "Unterminated topic reference"!? My TVHC version 1.0 contains an ugly bug. Due to this bug you cannot quote brackets by using them twice. If your TVHC prints the upper error message look for the function scanForCrossRefs() in tvhc.cpp and patch it like this: Original version: if (line[i+1] == begXRef) { strdel(line, i, 1); ++i; } Patched version: if (line[i] == begXRef) // [i] instead of [i+1] { strdel(line, i, 1); ++i; } After having changed the source code you should recompile TVHC to enable the changes. TVHC prints the error message "Text too long"!? The file tvhc.h contains a constant number named bufferSize that defines the maximum size of the text buffer. This text buffer is a little bit small. You should increase the buffer size e.g. to 32 KB to suppress the upper error message: const bufferSize = 32768; After having changed the buffer size you should recompile TVHC to enable the changes. TVHC prints the error message "TOPIC expected"!? This error message is printed if a line starts with a point. The point is a special character in Turbo Vision Help if it is the first character of a line. My TVHC stops if it reads such a line. But there's no need to stop the conversion. Thus I have patched my TVHC. I have replaced this line error("TOPIC expected"); with warning("TOPIC expected"); If you recompile the TVHC it will print a warning and it will go on converting the source file instead of printing an error message. A.12 Questions concerning Windows Help ======================================= WinHelp says that the RTF-File isn't a Windows Help file. Why? The RTF file UDO saves isn't a Windows Help file. It's just the source code of a Windows Help file! You have to convert this source code with the Microsoft Helpcompiler to get a Windows Help file. Where can I get the Microsoft Helpcompiler? You can download the Microsoft Helpcompiler HC31.EXE from Microsoft's FTP server (ftp.microsoft.com) free of charge. You shall find the HC where UDO is available, too. Why doesn't want the HC to compile UDO's output? This can have two reasons: 1. The UDO source file contains errors. Please take a look at UDO's log file (suffix `.ulw') and correct the errors you will find there. If the log file doesn't contain any error messages your source file may contain errors UDO hasn't detected. 2. The HC is working incorrectly. Take a look at the HC's error file (suffix `.err'). Unfortunately I can't tell you the sense of the errors printed in the error file in most cases. What is the file `.hpj' good for? When converting to Windows Help UDO will save an RTF file and a project file for the Microsoft Helpcompiler named `.hpj'. You have to start the HC by passing the name of this project file to get a Windows Help file. This project file contains several information e.g. the title of the help file, code for adding additional buttons, the size of the main window when opening the help file. UDO will overwrite this project file without previously asking you if you want it. So, if you have changed the project file and you want to protect your changes you have to write protect the project file. How does UDO generate headlines? UDO prints on every page (without the title page and the table of contents) a headline. In this headline the chapter name is printed inside a non-scrolling region. Thus you can see always the chapter name even if you scroll the text. If you use the switch !no_headlines [win] inside the preamble no headlines will be printed. If you use the command !ignore_headline inside a chapter in this chapter no headline will be printed. How does UDO create the context strings? If you want to create a link from another help file or a program to a help file that was made with UDO you have to know how UDO creates the context strings. Windows Help doesn't allow to use special characters inside context strings. UDO creates the context strings in the following way: 1. Special characters are printed in RTF form. 2. Blanks will be replaced by underscores. 3. All other characters except numbers and letters will be replaced by their hexadecimal value with a leading underscore. An example with German words: UDO: !node LaTeX-EinfÏhrung Teil 1 WinHelp: #{footnote # LaTeX_2DEinf_5C_27FChrung_Teil_1} Description: 1. The hexadecimal ASCII code of the dash is `0x2D'. The dash will be replaced by `_2D'. 2. The `Ï' inside `EinfÏhrung' is printed in RTF files like `\'FC'. The ASCII code of the backslash (`\') is `0x5C', so the backslash will be replaced by `_5C'. The ASCII code of `'' is `0x27', so the apostrophe will be replaced by `_27'. 3. The blanks will be replaced by `_' Thus the single letter "Ï" will be replaced by the really long string `_5C_27FC' wird. Maybe you want to say that this is quite awkward but if UDO would simply replace the "Ï" by "FC" problems would appear very soon. Using the upper way the chance that UDO creates a context string that is already used is very small. Why doesn't UDO center tables? It's impossible to center table in Windows Help. Why are there no lines inside tables? Windows Help doesn't allow it to layout complex tables like in RTF. It's impossible to tell Windows Help where to draw lines. It's only possible to tell Windows Help to print table cells with or without frames. Indents in lists and cells in tables are too width, why? UDO doesn't know the width of the characters you use inside lists and tables. Thus UDO is forced to calculate with values so that even bold and italic capital letters will fit the cells. I think that it's better to have cells with a width that is too large than too small. How can I print graphic characters from the IBM-PC character set? Sorry, there's no way to print them. I don't know the reason but Windows Help won't use the fonts "Terminal" or "MS LineDraw". Windows Help will always use another font if you want to use the upper fonts that contain the graphic characters. Thus UDO will replace the graphic characters of the IBM-PC character set by "+", "-" or "|". ====================================================================== Appendix B Bugs ====================================================================== The following known bugs will be fixed as fast as possible: Text styles inside indices: Inside indices you cannot use text styles at the moment. You can avoid this problem of you use the text style commands outside the (!idx ...) placeholder. Images & emTeX: The output of LaTeX commands for displaying MSP and PCX images with emTeX wasn't tested enough. If you have problems printing the images use the switch !no_images [tex] inside the preamble and write your own commands inside a raw environment. Small mistakes when layouting WinHelp: If you use many chapters and the chapter numbers become "too wide" there may be wrong indents in the tables of contents. You can avoid this by using the switch !no_numbers [win] in the preamble. Tables of contents: In the tables of contents long chapter titles aren't sized to the current document width yet. Chapter titles may also appear in different columns ("1.9"-"1.10" problem). If you detect another bug please let me (see "Contact addresses") know. Please add the following details to your bug report: ü Which UDO version do you use? ü On which operating system do you use UDO? ü Does the bug appear every time or only sometimes? ü Do you have an idea why UDO is working incorrectly? ü Can you give me a short example where I can reproduce the bug? ü If the error is format specific what do you think UDO should output? ====================================================================== Appendix C Error messages ====================================================================== UDO prints all error messages, warnings and hints that appear when converting the source file to files with the suffix .ul?. Each message is constructed the following way: Error: : Warning: : Hint: : If you want to avoid these errors, warnings and hints open the printed file, go to the printed line and try to find the error. Start with the first printed error and convert your source file once again. A lot of messages will disappear because they depend on earlier errors. `...' called twice The printed command was used twice or more inside the source file even if it's only to use it once. `...' expected UDO has expected the printed command. Please check if all envi- ronments were finished with the correct command or if a !begin_* is missing. `...' followed by `...' You have finished an environment with an incorrect command or you have forgotten to finish it. Another possibility is that you have misplaced the !end_* command. `...' ignored inside preamble It's only allowed to use the printed command inside the main part of the source file. That means you have to place it after !begin_document. `...' ignored outside preamble It's only allowed to use the printed command inside the preamble of the source file. That means you have to place it before !begin_document. `...' maybe not available in LaTeX The printed character cannot be used for LaTeX. Please try to use another character. `...' not active A text style or a footnote shall be finished even if it isn't active. Please note that the placeholders contain a capital letter for activating a text style. The placeholders that finish a text style contain a small letter. `...' not available in ISO Latin 1 ISO Latin1 doesn't contain the printed character. Thus, UDO cannot convert the printed character. `...' not available in this charset The printed character isn't available in the system character set. Thus, UDO cannot convert it. Please try to avoid the printed character. `...' still active A text style or a footnote shall be started even if it's still active. Please note that the placeholders contain a capital letter for activating a text style. The placeholders that finish a text style contain a small letter. `...' without `...' You wanted to finish an environment even if it wasn't startet before. !else without !if You have used the !else command but you haven't startet a query with !if, !ifdest etc. !endif without !if Your source file contains an !endif command but you haven't startet a query with !if, !ifdest etc. `!item' outside environment You have used the !item command outside an itemization, enumeration, description or list. check this paragraph UDO prints a filename and a line number where you can find the reason for the upper printed error message. couldn't open (pass1) UDO couldn't open the printed file in the first of two passes. couldn't open (pass2) UDO couldn't open the printed file in the second pass. Please check the filename you have used for !include. couldn't open destination file UDO couldn't open the destination file. Please check the filename or remove file protection of the existing file. couldn't open hypfile UDO couldn't open the hyphenation file. Please check the filename or remove file protection of the existing file. couldn't open logfile UDO couldn't open the log file. Please check the filename or remove file protection of the existing file. couldn't open source file UDO couldn't open the source file. Please check the filename. couldn't open treefile UDO couldn't open the tree file. Please check the filename or remove file protection of the existing file. couldn't read BMP header The printed file isn't a Windows Bitmap or the file doesn't exist. couldn't read IMG header The printed file isn't a GEM image or the file doesn't exist. couldn't read MSP header The printed file isn't a MSP image or the file doesn't exist. couldn't read PCX header The printed file isn't a PCX image or the file doesn't exist. couldn't replace (!ilink ...) A manual image link couldn't be replaced. You are allowed to use up to 200 internal and external links and internal images inside each paragraph. Split up the paragraph in two or more parts or delete some links. couldn't replace (!img ...) An internal image couldn't be replaced. You are allowed to use up to 200 internal and external links and internal images inside each paragraph. Split up the paragraph in two or more parts or delete some links. couldn't replace (!link ...) A manual link couldn't be replaced. You are allowed to use up to 200 internal and external links and internal images inside each paragraph. Split up the paragraph in two or more parts or delete some links. couldn't replace (!xlink ...) An external link couldn't be replaced. You are allowed to use up to 200 internal and external links and internal images inside each paragraph. Split up the paragraph in two or more parts or delete some links. couldn't write IMG header UDO couldn't open the printed file for changing the image information. Maybe the file doesn't exist or it's write protected. definition contents longer than ... characters The contents of a definition exceeds the maximum number of char- acters. Please shorten your definition contents. definition name longer than ... characters The name of a definition exceeds the maximum number of charac- ters. Please shorten your definition name. language ... not supported The printed language isn't supported by UDO yet or you have written the language in a wrong way. link destination undefined The destination of a manual link isn't defined. That means there's no chapter or label exisiting with the given name. macro contents longer than ... characters The contents of a macro exceeds the maximum number of characters. Please shorten your macro contents. macro name longer than ... characters The contents of a macro exceeds the maximum number of characters. Please shorten your macro name. memory allocation failed UDO couldn't allocate the needed memory. It doesn't stop converting the source file but you should take a look at the des- tination file if it's OK. missing parameter(s) A command needs a specific numer of parameters and you have used not enough parameters. Check the command and add the needed parameters. odd number of '' The source file contains an odd number of double apostrophes. UDO will find this error at the end of a chapter so check the chapter above the printed line number. odd number off "" The source file contains an odd number of double quotes. UDO will find this error at the end of a chapter so check the chapter above the printed line number. overfull line A line of a verbatim environment is longer than the value of !parwidth. Try to cut the line or increase the paragraph width. source and destination file are equal You have tried to read and write the same file. Check your command line options. string buffer overflow Please contact the author. too many aliases used Your source file contains too many !alias commands. Please delete some unimportant aliases or contact the author to get a special version of UDO. too many columns used Your source file contains a table with too many columns. too many defines used Your source file contains more than 128 definitions. too many environments used You have used too many environments into one another. Try to layout your source file less complex. too many files opened During the conversion too many files were opened. Check your source file if you constructed a recursive include. too many hyphens used Your source file contains too many syllabification patterns. Delete some of them and use local syllabification marks. too many items inside enumeration You have used too many items inside an enumerate environment where items are marked with letters. Reduce the ammount of items to 26 or use an itemize environment instead. too many labels used Your source file contains too many !label commands. Because UDO handles chapters and aliases like labels, too, this error message can appear when using only some labels. Please delete some unimportant labels or aliases or contact the author to get a special version of UDO. too many macros used Your source file uses more than 128 macros. too many nodes used Your source file uses too many chapters. If possible try to merge some chapters or contact the author to get a special version of UDO. too many parameters used A command or placeholder was called with too many parameters. Check the command and look for additional information inside the command index. too many rows used Your source file uses a table with too many rows. too many words used inside paragraph A paragraph of your source file uses too many words. Try to split up the paragraph into two or more parts. underfull line The printed line is too short and you will see an ugly right margin. If you use justification this error message says that there were inserted too many blanks. Try to insert syllabifi- cation marks or use the !sloppy command to suppress this type of error message. unexpected end of line in command Your source file contains a placeholder that wasn't finished correctly. unknown command UDO doesn't know the printed command. If you want to use a word a the beginning of a line that begins with an exclamation mark you have to mark it with a slash (`/'). use (!V) and (!v) in one line Something's still missing here... use (!xlink [text] [topic@foo.hlp]) The construction of an external link for Windows Help is incorrect. wrong number of parameters You called a command or placeholder with the wrong number of parameters. Check the command index for additional information. xlink needs WinHelp destination topic The construction of an external link for Windows Help is incorrect. Here the name of the page is missing. xlinks needs WinHelp destination file The construction of an external link for Windows Help is incorrect. Here, the name of the Windows Help file is missing. ====================================================================== Appendix D This & that ====================================================================== D.1 Facts, facts, facts ======================== You can use source files that don't exceed these maximum values: Macros: 128 Defines: 128 Hyphenation patterns: 4096 Sum of chapters, labels and aliases: 6144 Characters per line: 512 Characters per word: 128 Syllables per word: 32 Words per paragraph: 800 Links per paragraph: 200 Rows per table: 256 Columns per table: 32 Depth of environments: 6 Do you know how much work it has been to program UDO and to write this documentation? Here's the answer: Source code: 820 KB German Documentation: 470 KB English Documentation: 420 KB D.2 Programming environment ============================ UDO has been developed using the following software: Atari: Pure C 1.1, Pure Profiler 1.0, MiNT-Libs PL 46, SysGem 2.03beta, Interface 2.3, Programming Tools by Julian F. Reschke, MagiC-PC 1.01 DOS: EMX-GCC 2.6.3 emxfix06, GDB 4.13, PFE HP-UX: GCC 2.7.2 Linux: GCC 2.7.2, S.u.S.E. Linux 4.3 Kernel 2.0.18, Joe Macintosh: CodeWarrior 9 (68K/PPC), ResEdit 2.1 Currently I develop UDO on a Pentium 133 running Windows 95 with the EMX-GCC and on my Compaq Contura 486-DX50 notebook running Linux. This documentation has been written with the following software: ü Joe Allan's Own Editor `Joe' for MS-DOS and Linux ü Allan Phillips' Programmer's File Editor `PFE' 0.06.01 (the best editor for Windows 3.1 and Windows 95 I know) ü Phoenix for Windows 3.11 by Application Systems Heidelberg (also available as Fuji Base 1.0) D.3 Generated files ==================== A short description of the files, UDO saves next to its log files: .1: Nroff .c: C source code .cmd: command file for the Pure C help compiler .txt: ASCII .hpj: project file for the Microsoft Help Compiler HC.EXE .htm(l): HTML .lyx: LyX .man: Manualpage .pas: Pascal source code .rtf: RTF or WinHelp source code or QuickView source code .scr: Pure C Help source code .sgm(l): Linuxdoc-SGML .stg: ST-Guide source code .txt: Turbo-Vision-Help source code .tex: LaTeX .texinfo: Texinfo Files with the suffix .ul? contain the error messages and warnings UDO prints while converting the source file. Files with the suffix .uh? contain the syllabification patterns UDO prints for ASCII, ST-Guide and Pure C Help. Files with the suffix .ut? contain the "include tree". The following suffixes appear if UDO saves a file that has to be converted with another software to get the final result: .err: log file of the Microsoft Help Compiler (HC.EXE) .h: C header file for Turbo Vision (TVHC.EXE) .hlp: Windows Help file (HC.EXE), Turbo Vision Help file (TVHC.EXE), Pure C Help file (HC.PRG) .hyp: ST-Guide hypertext (HCP.TTP) .ref: ST-Guide reference file (HCP.TTP) ====================================================================== Appendix E History ====================================================================== In this chapter you will find a short summary of all the changes in the past. E.1 Last minute changes ======================== In this section you will find all the changes that aren't discussed in the other parts of this documentation yet. 1. Destination format "NROFF" I don't know if UDO really saves NROFF or if it's TROFF or GROFF. But you can already use it to make simple manpages for Unix systems. 2. Destination formats "C source code" and "Pascal source code" Using these formats it's possible to edit a C or Pascal source code and its documentation in one file. UDO will print "normal" text using the comment characters of C or Pascal. The source code will be printed without conversion. 3. The sourcecode environment Lines that are part of a sourcecode environment will be printed for C and Pascal without any conversion. If you convert to "normal" formats, UDO prints the lines as they were part of a verbatim environment that is used inside a quote environment. A small example of a C source code written with UDO: !program Hello, world! !author Dirk Hagedorn !begin_document !node Hello, World This program is just for demonstrating the sourcecode environment. !begin_sourcecode #include int main ( void ) { printf("Hello, world!\n"); return 0; } !end_sourcecode !end_document E.2 Release 6 ============== UDO6 was released on January 3rd, 1997. You will find here a very compressed list of the major changes of the last eight months. UDO supports now more destination formats, it supports new features and there were fixed a lot of bugs. In some cases it was impossible not to change the syntax of some commands. New destination formats: ü Apple QuickView ü HP-HelpTag-SGML (rudimentÌr) ü LyX ü C and Pascal source code (see "Last minute changes") ü NROFF (see "Last minute changes") New commands: ü !autoref_items [off|on]: Shall UDO insert links in items of descriptions and lists? ü !code_mac, !code_hp8, !code_iso, !code_dos and !code_tos: UDO understands now the character sets of other operating systems. ü !country: Additional title page information. ü !html_backpage: For a back-link on the HTML title page. ü !html_keywords: For HTML meta information. ü !html_img_suffix: To enable you to use JPEG images etc. ü !html_nodesize: For changing the font size of HTML headlines. ü !ifos und !ifnos: For checking the operatin system. ü !ignore_headline, !ignore_bottomline: For suppressing the headline or the bottomline of a specific node. ü !ignore_subtoc und Verwandte: For suppressing the sub-table of contents inside a specific node. ü !ignore_links: For suppressing links to a specific node. ü !image*: For printing image captions without "Figure #:". ü !image_counter: For changing the image counter. ü !no_index: For suppressing index command conversion. ü !no_toc_subnodes, !no_toc_subsubnodes, !no_toc_subsubsubnodes: For making the table of contents smaller. ü !no_preamble: Useful if you want to write your own preamble. ü !parwidth: For changing the paragraph width of the destina- tion file. ü !rtf_charwidth: For changing the value UDO uses for calulating indents and cell widths. ü !set, !unset, !ifset, !ifnset: For setting and checking symbols. ü !sort_hyphen_file: Shall UDO sort the hyphen file and delete duplicates? ü !subsubsubnode und Verwandte: A fourth layer. ü !table_counter: For changing the table counter. ü !table_caption*: For printing table captions without "Table #:". ü !tabwidth: For setting the tabulator width for verbatim en- vironments. ü !use_justification: Shall UDO generate justification? ü !use_nodes_inside_index, !use_alias_inside_index, !use_label_inside_index: For appending nodes, aliases and labels to the index. ü !use_output_buffer: Shall UDO use a buffer to make the referencation more perfectly for HTML and Windows Help? ü !use_short_envs: For printing always compressed environ- ments. ü !verbatimsize: For changing the font size of verbatim envi- ronments. ü !win_background: For changing the background colour for Windows Help. ü !win_high_compression, !win_medium_compression: For setting the compression rate for Windows Help. ü !win_inline_bitmaps: Shall UDO use special RTF commands for using inline bitmaps? ü !win_charwidth: For changing the value UDO uses for calulating indents and cell widths. News: ü You can use four layers now for structuring your text. ü Justification ü Macros and definitions can contain parameters. Thus, you can write your own commands in most cases. ü blist environment, ilist environment and tlist environment ü right justified text (flushright environment) ü left justfied text (flushleft environment) for suppressing the justification ü You can use up to four E-Mail addresses on the title page now. ü UDO supports Italian (!language italian), Spanisch (!language spanish) and Swedish (!language swedish) now. ü UDO can sort the hyphen file and delete duplicates. ü !no_umlaute converts now all international characters, not only the German umlauts. ü The source code was optimized. Although UDO supports lots of new commands this version of UDO runs faster than the old one. Changes: ü The RTF output was programmed completely new. You can import UDO's RTF files without problems in WinWord. ü UDO saves a preamble for LaTeX 2.09 and LaTeX2e on its own (you can switch it off, if you want). ü UDO allows you to use many more nodes, table rows, hyphens etc. ü UDO checks the source files more pedantically. ü Images are positioned like the outer text. To center an image you have to use the !image command inside a center en- vironment. Thus, you can print left and right justified images, too. ü The suffix for ASCII files is now .txt. ü UDO doesn't break line between \verb when converting to LaTeX. ü Graphic characters of the IBM PC character set will be replaced by `+', `-' and `|' for Windows Help. Syntax changes: ü !no_verbatim_umlaute replaces the switch !verbatim_no_umlaute ü The switch !list_parsep doesn't exist anymore. You can print "compressed" environment easier with !short now. ü The language of the destination file has to be set with the !language command now. !language english replaces the command !endlish. ü You can pass three index entries with one !index command now. ü !win_html_look doesn't exist anymore. ü Shdowed, hollow, outlined and framed text isn't supported anymore. But you can define your own commands with definitions if you need these text styles. E.3 Release 5 ============== A very short description of the major changes I added to this release for the last five months is listed here. It wasn't possible to prevent a change of the syntax of some commands. New destination formats: ü Linuxdoc-SGML ü Turbo Vision Help ü Texinfo New commands: ü !alias ü !begin_raw, !end_raw inside the raw environment you can enter special commands for a destination format ü !begin_table, !end_table setting tables like in LaTeX! ü !chapterimage an image can be used for the title of a chapter ü !define ü !french for French expressions ü !heading, !subheading, !subsubheading for displaying headlines ü !hline for displaying horizontal lines ü !htmlname to set the filename of a chapter ü !html_merge_nodes, !html_merge_subnodes, !html_merge_subsubnodes for merging chapters when converting to HTML ü (!ilink ...) for displaying images with links inside the text, Windows Help and HTML only ü (!img ...) for displaying images inside the text, Windows Help and HTML only ü !index for setting an index entry ü !list_parsep for switching the use of empty lines between items of an en- vironment ü !ifdest, !else, !endif for special passages ü !iflang, !else, !endif for special passages with different languages ü !node*, !subnode*, !subsubnode*, !pnode*, !psubnode*, !psubsubnode* for chapters that don't appear inside a table of contents ü !rinclude for including special commands ü !use_about_udo ü !use_chapter_images for displaying images instead of chapter titles ü !use_style_book ü !win_html_look for using grey inside a Windows Help file Changes: ü You can display tables very easily. You can define how to justify columns and where to draw horizontal and vertical lines. ü The layout of the environments was programmed completely new. Now you can use up to six environments inside another, the xlist environment, too! UDO generates a correct output for Windows Help and RTF. ü The semiautomatic syllabification was programmed completely new. ü UDO now references only complete words. ü You can use 1024 chapters and 1024 labels now. ü You can use up to 200 links inside a paragraph. Due to a bug you could only use 16 links inside a complete document in release 4. ü Manualpages are layouted completely new. ü Paintbrush PCX images are supported for emTeX. ü The output of Windows Help was updated in many cases! ü The Atari versions were compiled with MiNT libs PL46. Syntactical changes: ü The special environments that were built with !begin_*, !else_* and !end_* have to made with the more flexible commands !ifdest, !else and !endif. Instead of... !begin_asc [...] !else_asc [...] !end_asc ... you now have to use this construction: !ifdest [asc] [...] !else [...] !endif Bug fixes: Innumerous. ;-) E.4 Release 4 ============== This was the first English version with an English documentation! E.5 Release 3 ============== I think that nobody is interested in those things that changed a year ago. ====================================================================== Appendix F Command index ====================================================================== In this chapter you will find a short description of every UDO command in alphabetical order. The command description shows you the meaning of the descriptions. Command description =================== Type & position: The type of the command and the position where it's allowed to use it. A command tells UDO do something especially, a switch sets some internal information for UDO and a placeholder will be simply replaced by a different text fragment. "Preamble" means that you are only allowed to use this command in the preamble of your source file (before !begin_document). "Main part" means that you are only allowed to use it behind !begin_document. "Preamble & main part" means that you can use this command wherever you want. Syntax: Here you can see how to use the command. replaces text replaces a file name replaces a number replaces a single character replaces the abbreviation of the destination formats (aqv = Apple QuickView, asc = ASCII, htag = HP-Helptag-SGML, html = HTML, info = Texinfo, ldoc = Linuxdoc-SGML, lyx = LyX, man = Manualpage, pch = Pure-C-Help, rtf = RTF, stg = ST-Guide, tex = LaTeX, tvh = Turbo-Vision-Help, win = WinHelp) replaces the abbreviation of the destination language (english = English, french = French, german = German, italian = Italian, spanish = Spanish, swedish = Swedish) replaces one or more operating systems (beos = BeOS, dos = DOS, hpux = HP-UX, linux = Linux, macos = MacOS, nextstep = NeXTStep, sinix = SINIX, sunos = SunOS, tos = TOS) Example: Here you can see a small example. See also: Related commands and topic are listed here. F.1 A... ========= F.1.1 !=aqv ------------ Type & position: command, preamble & main part Syntax: !=aqv Description: "" will only be printed if you don't convert into Apple QuickView. "" will be not converted! See: !aqv, !ifdest, raw environment F.1.2 !=asc ------------ Type & position: command, preamble & main part Syntax: !=asc Description: "" will only be printed if you don't convert into ASCII. "" will be not converted! See: !asc, !ifdest, raw environment F.1.3 !alias ------------- Type & position: command, main part Syntax: !alias Description: "" is used as a secondary name of a chapter. UDO references an alias like a label or node name. You can use !alias inside a chapter more than once. But you should use only once. See: !node, !subnode, !subsubnode, !subsubsubnode, !label, Links, Labels F.1.4 !aqv ----------- Type & position: command, preamble & main part Syntax: !aqv Description: "" will only be printed if you convert into Apple QuickView. "" will be not converted! See: !=aqv, !ifdest, raw environment F.1.5 !asc ----------- Type & position: command, preamble & main part Syntax: !asc Description: "" will only be printed if you convert into ASCII. "" will be not converted! See: !=asc, !ifdest, raw environment F.1.6 !author -------------- Type & position: command, preamble Syntax: !author Description: "" will be used as the name of the author on the title page and for different other purposes. Example: !author Dirk Hagedorn See: !maketitle, !authorimage, Title page F.1.7 !authorimage ------------------- Type & position: command, preamble Syntax: !authorimage Description: will be displayed above the name of the author on the title page if the destination format supports images. Example: !authorimage dh See: !maketitle, !author, Title page, Images F.1.8 !autoref --------------- Type & position: switch, main part Syntax: !autoref [ on | off ] Description: Switches on or off automatic references. When UDO starts it will insert references automatically by default. For the ST-Guide UDO prints @autorefon or @autorefoff. Example: !autoref [off] See: Links F.1.9 !autoref_items --------------------- Type & position: switch, main part Syntax: !autoref_items [ on | off ] Description: With this command you can switch on or off if UDO shall insert links in items of a description envi- ronment or xlist environment. When UDO starts it inserts links by default. Example: !autoref_items [off] See: Descriptions, Lists, !item [ ] F.1.10 (!alpha) ---------------- Type & position: placeholder, preamble & main part Syntax: (!alpha) Description: This placeholder will be replaced by an alpha. Example: (!alpha) becomes alpha See: (!beta), Special characters F.2 B... ========= F.2.1 !begin_appendix ---------------------- Type & position: command, main part Syntax: !begin_appendix Description: Starts the appendix. Chapters are enumerated with letters. UDO supports only one appendix per source file! See: !end_appendix, Appendix F.2.2 !begin_blist ------------------- Type & position: command, main part Syntax: !begin_blist [] Description: Starts a new list. The length of "" defines the indent of the list. This environment must be finished with !end_blist. You can use this environ- ment inside other environments. The text you set with !item [ ] will be displayed with a bold font. See: !end_blist, !item [ ], !begin_ilist, !begin_tlist, !begin_xlist, Lists F.2.3 !begin_center -------------------- Type & position: command, main part Syntax: !begin_center Description: This command opens a (new) center environment. Text that is part of a center environment will be printed centred until the !end_center command appears. UDO layouts the text of a center environment so you will may be be forced to insert manual linebreaks with (!nl). See: !end_center, (!nl) F.2.4 !begin_description ------------------------- Type & position: command, main part Syntax: !begin_description Description: Starts a new description environment that has to be finished with !end_description. You can use the description environment inside other (description) environments. Text that stands between the brackets of !item [ ] will be printed with bold text. See: !end_description, !item [ ], Descriptions, !short F.2.5 !begin_document ---------------------- Type & position: command, main part Syntax: !begin_document Description: This command must be part of every source file. It divides the preamble from the main part. See: !end_document F.2.6 !begin_enumerate ----------------------- Type & position: command, main part Syntax: !begin_enumerate Description: Starts a new enumerate environment that has to be finished with !end_enumerate. You can use the enumerate environment inside other (enumerate) envi- ronments. The items of an enumerate environment will be marked with alphanumerical characters. See: !end_enumerate, !item, Enumerations, !short F.2.7 !begin_flushleft ----------------------- Type & position: command, main part Syntax: !begin_flushleft Description: Lines that are part of flushleft environment are printed left justified without justification. See: !end_flushleft F.2.8 !begin_flushright ------------------------ Type & position: command, main part Syntax: !begin_flushright Description: Lines that are part of flushright environment are printed right justified without justification. See: !end_flushright F.2.9 !begin_ilist ------------------- Type & position: command, main part Syntax: !begin_ilist [] Description: Starts a new list. The length of "" defines the indent of the list. This environment must be finished with !end_ilist. You can use this environ- ment inside other (iltalic list) environments. The text you set with !item [ ] will be displayed with an italic font. See: !end_ilist, !item [ ], !begin_blist, !begin_xlist, !begin_tlist, Lists F.2.10 !begin_itemize ---------------------- Type & position: command, main part Syntax: !begin_itemize Description: Starts a new itemize environment that has to be finished with !end_itemize. You can use the itemize environment inside other (itemize) environments. Items of the itemize environment will be marked with bullets, dashes or stars. See: !end_itemize, !item, Itemizations, !short F.2.11 !begin_quote -------------------- Type & position: command, main part Syntax: !begin_quote Description: This command starts a new quote environment. Text is printend indented until UDO reads the !end_quote command. See: !end_quote, Indented paragraphs F.2.12 !begin_raw ------------------ Type & position: command, preamble & main part Syntax: !begin_raw Description: Starts a raw environment that has to be finished with !end_raw. Each line inside this environment will be output directly without any conversion. Thus this environment can be used to insert specific commands for the destionation format. See: !end_raw, raw environment, !rinclude, !ifdest F.2.13 !begin_sourcecode ------------------------- Type & position: command, main part Syntax: !begin_sourcecode Description: With this command you can start a sourcecode envi- ronment. It has to be finished with the !end_sourcecode command. Lines that are part of a sourcecode environment will be printed without conversion for the sourcecode formats. For the "normal" formats the text of the sourcecode environ- ment will be printed like text of a verbatim envi- ronment that is used inside a quote environment. See: !end_sourcecode F.2.14 !begin_table -------------------- Type & position: command, main part Syntax: !begin_table [] {!hline} Description: With this command a table is started. For you enter the justification of the columns of this table and the position of vertical lines. If this command is followed by `!hline' the table starts with a horizontal line. The example shows how to make a table with three columns where the left column is left justified, the second is centered and the last columns is right justified. The table begins with a horizontal line an it has one vertical line on the left Example: !begin_table [|lcr|] !hline See: !hline, !end_table, Tables F.2.15 !begin_tlist -------------------- Type & position: command, main part Syntax: !begin_tlist [] Description: Starts a new list. The length of "" defines the indent of the list. This environment must be finished with !end_tlist. You can use this environ- ment inside other environments. The text you set with !item [ ] will be displayed with a monospaced font. See: !end_tlist, !item [ ], !begin_blist, !begin_ilist, !begin_xlist, Lists F.2.16 !begin_verbatim ----------------------- Type & position: command, main part Syntax: !begin_verbatim Description: Starts a verbatim environment that has to be finished with !end_verbatim. Text that is part of a verbatim environment is printed out as given using a monospaced font. See: !end_verbatim, Preformatted text, !vinclude F.2.17 !begin_xlist -------------------- Type & position: command, main part Syntax: !begin_xlist [] Description: Starts a new list. The length of "" defines the indent of the list. This environment must be finished with !end_xlist. You can use this environ- ment inside other environments. The text you set with !item [ ] will be displayed with the normal font. See: !end_xlist, !item [ ], !begin_blist, !begin_ilist, !begin_tlist, Lists F.2.18 !bigskip ---------------- Type & position: command, main part Syntax: !bigskip Description: This command will be simplay replaced by "\bigskip" when converted to LaTeX. Otherwise three additional empty lines will be generated. See: !smallskip, !medskip F.2.19 !break -------------- Type & position: command, main part Syntax: !break Description: You can use this command inside the source file to stop the conversion right at the line where you use this command. UDO calls !end_appendix and !end_document itself if necessary. F.2.20 (!B)...(!b) ------------------- Type & position: placeholder, preamble & main part Syntax: (!B)(!b) Description: "" will be displayed in bold text if possible. Example: (!B)bold(!b) See: Emphasizing text F.2.21 (!beta) --------------- Type & position: placeholder, preamble & main part Syntax: (!beta) Description: This placeholder will be replaced by beta. Example: (!beta) becomes beta See: (!alpha), Special characters F.3 C... ========= F.3.1 !chapterimage -------------------- Type & position: command, main part Syntax: !chapterimage Description: Converting to Windows Help, HTML or ST-Guide the image called `' is displayed instead of the chapter title if !use_chapter_images is used inside the preamble. Example: !chapterimage udo See: Images, !use_chapter_images F.3.2 !code_dos ---------------- Type & position: switch, preamble & main part Syntax: !code_dos Description: UDO expects files written in the IBM-PC character set after this command. You can switch back to your system charset with some other commands (see below). See: !code_iso, !code_mac, !code_hp8, !code_tos, Special characters F.3.3 !code_hp8 ---------------- Type & position: switch, preamble & main part Syntax: !code_hp8 Description: UDO expects files written in the HP Roman 8 charac- terset after this command. You can switch back to your system charset with some other commands (see below). See: !code_dos, !code_iso, !code_mac, !code_tos, Special characters F.3.4 !code_iso ---------------- Type & position: switch, preamble & main part Syntax: !code_iso Description: UDO expects files written in the ISO characterset or Windows ANSI characterset after this command. You can switch back to your system charset with some other commands (see below). See: !code_dos, !code_mac, !code_hp8, !code_tos, Special characters F.3.5 !code_mac ---------------- Type & position: switch, preamble & main part Syntax: !code_mac Description: UDO expects files written in the Macintosh character set behind this command. You can switch back to your system charset with some other commands (see below). See: !code_dos, !code_iso, !code_hp8, !code_tos, Special characters F.3.6 !code_tos ---------------- Type & position: switch, preamble & main part Syntax: !code_tos Description: UDO expects files written in the Atari ST charac- terset behind this command. You can switch back to your system charset with some other commands (see below). See: !code_dos, !code_iso, !code_mac, !code_hp8, Special characters F.3.7 !country --------------- Type & position: command, preamble Syntax: !country Description: "" will be displayed below the town of the author on the title page to show in which country he lives. Example: !country Germany See: !maketitle, Title page F.3.8 (!copyright) ------------------- Type & position: special character(s), preamble & main part Syntax: (!copyright) Description: This placeholder will be replaced by a special copyright symbol if the destination format supports them. If it doesn't UDO will replace this placeholder by "(c)". Example: (!copyright) is converted to (c) F.4 D... ========= F.4.1 !date ------------ Type & position: command, preamble Syntax: !date Description: "" will be displayed on the title page below the contents of !version. The example shows how to use the current system time for the title page. Example: !date (!today) See: !maketitle, (!today), (!short_today), Title page F.4.2 !define -------------- Type & position: command, preamble Syntax: !define Description: Sets a (new) definition. When converting UDO will replace every "(!)" by "" without converting special chars. When using the lower exmaple every "(!H1)" will be replaced by "". The difference to a macro: no umlauts or other special chars will be converted. Definitions can contain parameters. Read the chapter "Definitions" to get to know how to use definitions with parameters. Example: !define H1 See: Definitions F.5 E... ========= F.5.1 !else ------------ Type & position: command, preamble & main part Syntax: !else Description: The following lines are converted until the appearance of !endif, if the abbreviation of the current destination format wasn't used with the previous !ifdest or !iflang command. See: !ifdest, !iflang, !endif, Query commands F.5.2 !email ------------- Type & position: command, preamble Syntax: !email Description: "" will be dsiplayed on the titlepage below the name and address of the author. !email can be used up to four times to enable you to print more than one email address on the title page. Example: !email Internet: dh@mk2.maus.sauerland.de See: !maketitle, Title page F.5.3 !end_appendix -------------------- Type & position: command, main part Syntax: !end_appendix Description: This command finishes the appendix. UDO supports only one appendix, so this command should be the precessor of !begin_document. See: !begin_appendix, Appendix F.5.4 !end_blist ----------------- Type & position: command, main part Syntax: !end_blist Description: Finsihes the latest blist ("bold list") environment. See: !begin_blist, !item [ ], Lists F.5.5 !end_center ------------------ Type & position: command, main part Syntax: !end_center Description: This command finishes the latest center environment. See: !begin_center, center environment F.5.6 !end_description ----------------------- Type & position: command, main part Syntax: !end_description Description: This command finishes the latest descripion environ- ment. See: !begin_description, !item [ ], description environ- ment F.5.7 !end_document -------------------- Type & position: command, main part Syntax: !end_document Description: This command must be part of a source file and it should be the last command. If you forget to use this command UDO will print an error message. See: !begin_document F.5.8 !end_enumerate --------------------- Type & position: command, main part Syntax: !end_enumerate Description: Finishes the latest enumerate environment. See: !begin_enumerate, !item, enumerate environment F.5.9 !end_flushleft --------------------- Type & position: command, main part Syntax: !end_flushleft Description: This command finishes the latest flushleft environ- ment. See: !begin_flushleft, flushleft environment F.5.10 !end_flushright ----------------------- Type & position: command, main part Syntax: !end_flushright Description: This command finishes the latest flushright environ- ment. See: !begin_flushright, flushright environment F.5.11 !end_ilist ------------------ Type & position: command, main part Syntax: !end_ilist Description: Finishes the latest ilist ("italic list") environ- ment. See: !begin_ilist, !item [ ], Lists F.5.12 !end_itemize -------------------- Type & position: command, main part Syntax: !end_itemize Description: Finishes the latest itemize environment. See: !begin_itemize, !item, itemize environment F.5.13 !end_quote ------------------ Type & position: command, main part Syntax: !end_quote Description: This command finishes the last quote environment. Text, that's part of a quote environment will be displayed indented. See: !begin_quote, quote environment F.5.14 !end_raw ---------------- Type & position: command, preamble & main part Syntax: !end_raw Description: Finishes the raw environment. See: !begin_raw, raw environment F.5.15 !end_sourcecode ----------------------- Type & position: command, main part Syntax: !end_sourcecode Description: This command finishes the sourcecode environment. See: !begin_sourcecode F.5.16 !end_table ------------------ Type & position: command, main part Syntax: !end_table Description: Finishes the table environment and prints the table. See: Tables, !begin_table F.5.17 !end_tlist ------------------ Type & position: command, main part Syntax: !end_tlist Description: Finsihes the latest tlist environment. See: !begin_tlist, !item [ ], Lists F.5.18 !end_verbatim --------------------- Type & position: command, main part Syntax: !end_verbatim Description: Finishes the verbatim environment. See: !begin_verbatim, Preformatted text F.5.19 !end_xlist ------------------ Type & position: command, main part Syntax: !end_xlist Description: Finsihes the latest xlist environment. See: !begin_xlist, !item [ ], Lists F.5.20 !endif -------------- Type & position: command, preamble & main part Syntax: !endif Description: Finishes a query command that was started with !ifdest, !iflang, !ifset, !ifos or !if. See: !ifdest, !iflang, !ifset, !ifos, !if, !else, Query commands F.6 F... ========= F.6.1 !fussy ------------- Type & position: switch, main part Syntax: !fussy Description: Switches on warning messages according to short lines. You can use this command wherever you want. The warnings can be disabled with !sloppy. When converting to LaTeX UDO doesn't convert !fussy into `\fussy'! See: !sloppy, Error messages, Syllabification F.7 G... ========= F.7.1 (!grin) -------------- Type & position: placeholder, preamble & main part Syntax: (!grin) Description: (!grin) will be replaced by a grinning emoticon displayed in typewriter. Example: (!grin) becomes ;-) See: (!laugh) F.8 H... ========= F.8.1 !=htag ------------- Type & position: command, preamble & main part Syntax: !=htag Description: "" will only be printed if you don't convert into Helptag. "" will be not converted! See: !htag, !ifdest, raw environment F.8.2 !=html ------------- Type & position: command, preamble & main part Syntax: !=html Description: "" will only be printed if you don't convert into HTML. "" will be not converted! See: !html, !ifdest, raw environment F.8.3 !heading --------------- Type & position: command, main part Syntax: !heading Description: This command prints out "" like a headline using the chapter font and fontsize. Example: !heading A headline See: !subheading, !subsubheading, !subsubsubheading F.8.4 !hline ------------- Type & position: command, main part Syntax: !hline Description: This command displays a horizontal line inside normal text or inside a table. Not all destination formats support horizontal lines. See: Tables F.8.5 !htag ------------ Type & position: command, preamble & main part Syntax: !htag Description: "" will only be printed if you convert into Helptag. "" will be not converted! See: !=htag, !ifdest, raw environment F.8.6 !htag_img_suffix ----------------------- Type & position: switch, preamble & main part Syntax: !htag_img_suffix Description: UDO uses the suffix "tiff" when converting the image commands for HP HelpTag SGML by default. If you want to use different image types you can redefine the image suffix with this command. The lower example shows how to change the image suffix to "xwd". You can use !htag_img_suffix as often as you want so you can redefine the image suffix right before every image. Example: !htag_img_suffix xwd See: !image, (!img [ ]), Images F.8.7 !html ------------ Type & position: command, preamble & main part Syntax: !html Description: "" will only be printed if you convert into HTML. "" will be not converted! Example: !html
See: !=html, !ifdest, raw environment F.8.8 !html_backpage --------------------- Type & position: command, preamble Syntax: !html_backpage Description: Using this command you can tell UDO where to jump to when the reader clicks on the "Go Up" button on the title page. Example: !html_backpage ../index.html See: !no_headlines, !no_bottomlines F.8.9 !html_img_suffix ----------------------- Type & position: switch, preamble & main part Syntax: !html_img_suffix Description: UDO uses the suffix "gif" when converting the image commands for HTML by default. If you want to use different image types you can redefine the image suffix with this command. The lower example shows how to change the image suffix to "jpeg". You can use !html_img_suffix as often as you want so you can redefine the image suffix right before every image. Example: !html_img_suffix jpeg See: !image, (!img [ ]), Images F.8.10 !html_keywords ---------------------- Type & position: command, main part Syntax: !html_keywords Description: Description: If you use this command inside a chapter, section, subsection or paragraph, "" is used as the name of the HTML file instead of CCSSUUPP (CC chapter, SS section, UU subsection, PP paragraph). Example: !html_name software F.8.16 !html_nodesize ---------------------- Type & position: switch, preamble Syntax: !html_nodesize Description: You can set the font size of the HTML headlines with this switch. By default UDO will use value of 1. That means, that UDO will print

...

for chapters,

...

for sections etc. The example shows how to tell UDO that it should print

...

for chapters etc. Example: !html_nodesize 2 See: !node, !subnode, !subsubnode, !subsubsubnode F.8.17 !html_use_xlist ----------------------- Type & position: switch, preamble Syntax: !html_use_xlist Description: Because the output of an xlist environment is very complicated these environments are handled like description environments by default. Use this switch inside the preamble to display xlist environments like in ASCII and with the use of the preformatted tag. See: Lists, Descriptions F.8.18 !hyphen --------------- Type & position: command, preamble Syntax: !hyphen Description: You can set syllabification marks (!-) with this command for a word for the whole text. The example shows how to tell UDO where it's allowed to split up the word "syllabification". Example: !hyphen syl!-labi!-fi!-ca!-tion See: Syllabification, !sloppy, !fussy, !- F.9 I... ========= F.9.1 !=info ------------- Type & position: command, preamble & main part Syntax: !=info Description: "" will only be printed if you don't convert into Texinfo "" will be not converted! See: !info, !ifdest, raw environment F.9.2 !if ---------- Type & position: command, preamble & main part Syntax: !if [] Description: This command combines the commands !ifdest, !iflang, !ifset and !ifos. The example shows how to test if the source file is converted into an English HTML file. Example: !if [english,html] See: !iflang, !ifdest, !ifset, !ifos, Query commands F.9.3 !ifdest -------------- Type & position: command, preamble & main part Syntax: !ifdest [] Description: This command tests the current destination format. If one of the "" matches the abbreviation of the destination format UDO will convert all lines between !ifdest and !else or !endif. If not UDO will only convert the lines between !else and !endif if !else is used. The example shows how to test if UDO converts to ST- Guide or Windows Help. Example: !ifdest [stg,win] See: !else, !endif, !ifndest, !if, Query commands F.9.4 !iflang -------------- Type & position: command, preamble & main part Syntax: !iflang [] Description: This command test the language UDO uses for the des- tination file. If "" matches one of the abbreviations for the destination languages UDO will convert all lines between !iflang and !else or !endif. If not UDO will only convert the lines between !else and !endif if !else is used. The example shows how to test if UDO converts to English. Example: !iflang [english] See: !ifnlang, !ifdest, !language, Query commands F.9.5 !ifndest --------------- Type & position: command, preamble & main part Syntax: !ifndest [] Description: This command tests the current destination format. If none of the "" match the abbreviation of the destination format UDO will convert all lines between !ifdest and !else or !endif. If one matches them UDO will only convert the lines between !else and !endif if !else is used. The example shows how to test if UDO doesn't convert to HTML. Example: !ifndest [html] See: !else, !endif, !ifdest, Query commands F.9.6 !ifnlang --------------- Type & position: command, preamble & main part Syntax: !ifnlang [] Description: This command tests the current destination language. If none of the "" match the abbreviation of the destination language UDO will convert all lines between !ifdest and !else or !endif. If one matches them UDO will only convert the lines between !else and !endif if !else is used. The example shows how to test if UDO doesn't convert to French. Example: !ifnlang [french] See: !ifnlang, !ifdest, !language, Query commands F.9.7 !ifnos ------------- Type & position: command, preamble & main part Syntax: !ifnos [] Description: This command tests the current operating system UDO is running on. If "" doesn't match any of the abbreviations of the operating systems UDO will convert all lines that follow !else if it is used. If !else isn't used UDO will ignore all lines until an !endif. The example shows how you can test if UDO !doesn't run on an Apple Macintosh. Example: !ifnos [macos] See: !ifos F.9.8 !ifnset -------------- Type & position: command, preamble & main part Syntax: !ifnset [] Description: With this command you can test if a symbol !wasn't set with the command line option -D or with !set. If wasn't set UDO will convert all lines bewteen !ifnset and !else or !endif. If was set UDO will convert all lines between !else and !endif if !else was used. The example shows how to test if the symbol "british" isn't set. Example: !ifnset [british] See: !ifset F.9.9 !ifos ------------ Type & position: command, preamble & main part Syntax: !ifos [] Description: This command tests the current operating system UDO is running on. If "" match one of the ab- breviations of the operating systems UDO will convert all lines that are used between !ifos and !endif or !else. If "" doesn't match any of the abbreviations of the operating systems UDO will ignore all lines before !endif or !else. The example shows how you can test if UDO runs with Linux. Example: !ifos [linux] See: !ifnos F.9.10 !ifset -------------- Type & position: command, preamble & main part Syntax: !ifset [] Description: With this command you can test if a symbol was set with the command line option -D or with !set. If was set UDO will convert all lines bewteen !ifset and !else or !endif. If wasn't set UDO will convert all lines between !else and !endif if !else was used. The example shows how to test if the symbol "british" was set. Example: !ifset [british] See: !ifnset F.9.11 !ignore_bottomline -------------------------- Type & position: switch, preamble Syntax: !ignore_bottomline Description: If this switch is used inside a chapter UDO won't print a headline. In contrast to !no_bottomlines this switch will only suppress the headline inside the chapter where !ignore_bottomline is used. See: !no_bottomlines F.9.12 !ignore_headline ------------------------ Type & position: switch, preamble Syntax: !ignore_headline Description: If this switch is used inside a chapter UDO won't print a headline. In contrast to !no_headlines this switch will only suppress the headline inside the chapter where !ignore_headline is used. See: !no_headlines F.9.13 !ignore_index --------------------- Type & position: switch, main part Syntax: !ignore_index Description: If this switch is used inside a chapter UDO won't add its title to the index even if the switch !use_nodes_inside_index is used inside the preamble of the source file. See: !use_nodes_inside_index, !no_index, Indices F.9.14 !ignore_links --------------------- Type & position: switch, main part Syntax: !ignore_links Description: If this switch is part of a chapter UDO won't insert links to this chapter automatically. You are still able to insert links with !link ...) on your own. See: Links, (!link ...) F.9.15 !ignore_subsubsubtoc ---------------------------- Type & position: switch, main part Syntax: !ignore_subsubsubtoc Description: If this switch is used inside a subsection UDO won't print a "subsubsubtoc" which contains all paragraphs of this subsection even if you have used !use_auto_subsubsubtocs inside the preamble. See: !use_auto_subsubsubtocs, !subsubsubtoc F.9.16 !ignore_subsubtoc ------------------------- Type & position: switch, main part Syntax: !ignore_subsubtoc Description: If this switch is used inside a section UDO won't print a "subsubtoc" which contains all subsections and paragraphs of this section even if you have used !use_auto_subsubtocs inside the preamble. See: !use_auto_subsubtocs, !subsubtoc F.9.17 !ignore_subtoc ---------------------- Type & position: switch, main part Syntax: !ignore_subtoc Description: If this switch is used inside a chapter UDO won't print a "subtoc" which contains all sections, subsections and paragraphs of this chapter even if you have used !use_auto_subtocs inside the preamble. See: !use_auto_subtocs, !subtoc F.9.18 !image -------------- Type & position: command, main part Syntax: !image Description: A command to include an image is generated in the destination file, if it supports images. You shouldn't pass the suffix of the wanted image because UDO itself adds the right one. It will be .img for the ST-Guide, CSTeX and Lindner-TeX, .gif for HTML, .msp or .pcx for emTeX and .bmp for Windows Help. If `' is used it will be printed as the title of this Example: !image tiger See: !no_images, (!image ...), Images, !html_img_suffix F.9.19 !image* --------------- Type & position: command, main part Syntax: !image* Description: There's one difference between !image* and !image. If you use this command there will be printed no table number. Example: !image* tiger This is a tiger See: !image F.9.20 !image_counter ---------------------- Type & position: switch, preamble Syntax: !image_counter [] Description: With this switch you can set the image counter. If you use the lower example the caption of the first image will look like this: "Figure 5: ...". Example: !image_counter 5 See: Images F.9.21 !include ---------------- Type & position: command, preamble & main part Syntax: !include Description: Opens the file named "file" and converts its contents. Example: !include macros.ui See: !vinclude, !rinclude, Split documents F.9.22 !index -------------- Type & position: command, main part Syntax: !index Description: will pe printed as \index {...} for LaTeX, K{\footnote K ...} for WinHelp, {\xe\v ...} for RTF and @index ... for ST-Guide. So, appears in the index of LaTeX and ST-Guide. WinHelp allows to search this word. You can use this command as many times as you like. Example: !index entry !! index See: Indices, !no_index F.9.23 !info ------------- Type & position: command, preamble & main part Syntax: !info Description: "" is only given out if you convert into Texinfo. "" will be not converted! See: !=info, !ifdest, raw environment F.9.24 !item ------------- Type & position: command, main part Syntax: !item Description: Starts a new item of an itemize or enumerate envi- ronment. Example: !item This is the next item See: !item [ ], Itemizations, Enumerations F.9.25 !item [ ] ----------------- Type & position: command, main part Syntax: !item [] Description: Starts a new item of a description or an xlist envi- ronment. "" will be displayed in bold text inside a description environment. Example: !item [Title:] Description See: !item, Descriptions, Lists F.9.26 (!I)...(!i) ------------------- Type & position: placeholder, preamble & main part Syntax: (!I)(!i) Description: "" will be displayed in italics if possible. Example: (!I)italic(!i) See: Emphasizing text F.9.27 (!idx ...) ------------------ Type & position: placeholder, main part Syntax: (!idx [] {[]} {[]} {[]} ) Description: Useful for adding indices right inside the source file. Example: (!idx [word] [index entry]) See: Indices, !no_index, !index F.9.28 (!ilink ...) -------------------- Type & position: placeholder, main part Syntax: (!ilink [] [] []) Description: This placeholder is a combination of (!img ...) and (!link ...) and is useful to display an image right inside the text. If you click this image you will jump to another part of the document. The example shows how to display an image called disk.[bmp,gif], the link destination is "Download". In HTML "download UDO" will be used as the alternative text. In all other formats only "download" UDO will be dislayed. Example: (!ilink [disk] [download UDO] [Download] See: (!img~..), (!link ...), Links, Images F.9.29 (!img ...) ------------------ Type & position: placeholder, main part Syntax: (!img [] []) Description: Use this placeholder to use an image right inside the text of HTML or WinHelp. If another destination format will be used only "" will be displayed. When converting to HTML file.gif will be used, when converting to WinHelp file.bmp will be used. UDO doesn't check if this file exists. Example: (!img [dh] [my logotype]) See: Images, !image F.10 L... ========== F.10.1 !=ldoc -------------- Type & position: command, preamble & main part Syntax: !=ldoc Description: "" will only be printed if you don't convert into Linuxdoc-SGML. "" will be not converted! See: !ldoc, !ifdest, raw environment F.10.2 !label -------------- Type & position: command, main part Syntax: !label Description: Defines a label that will be referenced in hypertexts or can be accessed by a link command Example: !label Label See: Labels, (!link ...), (!plink ...) F.10.3 !language ----------------- Type & position: command, preamble Syntax: !language [] Description: With this command you can tell UDO which language it should use for the date and expressions like "Table", "Contents" or "Appendix". UDO will use German expressions by default. The example shows how to change the language to English. Example: !language english See: !iflang, !ifnlang, (!today) F.10.4 !ldoc ------------- Type & position: command, preamble & main part Syntax: !ldoc Description: "" is only given out if you convert into Linuxdoc-SGML. "" will be not converted! See: !=ldoc, !ifdest, raw environment F.10.5 !listoffigures ---------------------- Type & position: command, main part Syntax: !listoffigures Description: This command prints a list of figures. You should use it directly after !tableofcontents if you want to use it. At the moment this command will only be converted for LaTeX. See: !image, !tableofcontents, !listoftables F.10.6 !listoftables --------------------- Type & position: command, main part Syntax: !listoftables Description: This command prints a list of tables. You should use it directly after !tableofcontents or !listoffigures if you want to use it. At the moment this command will only be converted for LaTeX. See: Tabellen, !tableofcontents, !listoffigures F.10.7 (!LaTeX) ---------------- Type & position: placeholder, preamble & main part Syntax: (!LaTeX) Description: This placeholder will be replaced by \LaTeX{} when converting to LaTeX. Otherwise it will be replace by "LaTeX". See: (!TeX), (!LaTeXe) F.10.8 (!LaTeXe) ----------------- Type & position: placeholder, preamble & main part Syntax: (!LaTeXe) Description: This placeholder will be replaced by \LaTeXe{} when converting to LaTeX. Otherwise it will be replace by "LaTeX2e". See: (!TeX), (!LaTeX) F.10.9 (!laugh) ---------------- Type & position: placeholder, preamble & main part Syntax: (!laugh) Description: (!laugh) will be replaced by a laughing emoticon displayed in typewriter. Example: (!laugh) becomes :-) See: (!grin) F.10.10 (!link~..) ------------------- Type & position: placeholder, main part Syntax: (!link [] []) Description: With this placeholder you can define links to other parts of the document. See section "Links" for further information. Example: (!link [me] [Contact addresses]) See: (!xlink ...), (!plink ...), Links F.11 M... ========== F.11.1 !=man ------------- Type & position: command, preamble Syntax: !=man Description: "" will only be printed if you don't convert into a manualpage. "" will be not converted! See: !man, !ifdest, raw environment F.11.2 !macro -------------- Type & position: command, preamble Syntax: !macro Description: Defines a macro. Later on every "(!)" will be replaced by "". When using the lower exmaple every "(!DH)" will be replaced by "Dirk Hagedorn". Example: !macro DH Dirk Hagedorn See: Macros F.11.3 !maketitle ------------------ Type & position: command, main part Syntax: !maketitle Description: Outputs a titlepage build with the information set by the lower commands. !maketitle should be used directly after !begin_document and before !tableofcontents. See: Title page F.11.4 !man ------------ Type & position: command, preamble & main part Syntax: !man Description: "" is printed if you convert into a manualpage. "" will be not converted! See: !=man, raw environment F.11.5 !man_lpp ---------------- Type & position: command, preamble Syntax: !man_lpp Description: Sets the "lines per page" of a manualpage. If is bigger than 0 UDO generates footlines with pagenumbers. When UDO starts !man_lpp is undefined and UDO won't generate these footlines. Example: !man_lpp 60 See: !use_formfeed F.11.6 !man_type ----------------- Type & position: command, preamble Syntax: !man_type Description: When converting into a manualpage UDO uses "" inside the headline with brackets. The exmaple and "!program udo" would look like "udo(1)". UDO doesn't use "" as a file suffix. Example: !man_type 1 F.11.7 !medskip ---------------- Type & position: command, main part Syntax: !medskip Description: This command will be simplay replaced by `\medskip' when converted to LaTeX. Otherwise two additional empty lines will be generated. See: !smallskip, !bigskip F.12 N... ========== F.12.1 !newpage ---------------- Type & position: command, main part Syntax: !newpage Description: Generates a page break if the destination format supports it. See: !use_formfeed F.12.2 !no_bottomlines ----------------------- Type & position: switch, preamble Syntax: !no_bottomlines [] Description: Tells UDO not to generate bottomlines. In the example this is done for the Pure C Help format. Example: !no_bottomlines [pch] See: !no_headlines, !ignore_bottomline F.12.3 !no_effects ------------------- Type & position: switch, preamble Syntax: !no_effects [] Description: Switches off the usage of text emphasises. The exmaple shows how to switch it of when converting to ASCII. Example: !no_effects [asc] F.12.4 !no_headlines --------------------- Type & position: switch, preamble Syntax: !no_headlines [] Description: Switches off the usage of headlines. The example show how to switch it off when converting to WinHelp. Example: !no_headlines [win] See: !no_bottomlines, !ignore_headline F.12.5 !no_images ------------------ Type & position: switch, preamble Syntax: !no_images [] Description: Switches off the output of commands to display images. The example show how to switch it off when converting to HTML. Example: !no_images [html] See: !image, Images F.12.6 !no_index ----------------- Type & position: switch, preamble Syntax: !no_index [] Description: If this switch is used inside the preamble UDO suppresses index commands for the given destination formats. Furthermore neither UDO nor the destination format will print an index. The example shows how to suppress index commands for RTF. Example: !no_index [rtf] See: !index, (!idx ...) F.12.7 !no_numbers ------------------- Type & position: switch, preamble Syntax: !no_numbers [] Description: This command switches off the usage of chapter numbers. In tables of contens only the chapter titles will be displayed. The example shows how to suppress them in Windows Help and HTML. Example: !no_numbers [win,html] See: !tableofcontents, !toc, !subtoc, !subsubtoc F.12.8 !no_preamble -------------------- Type & position: switch, preamble Syntax: !no_preamble [] Description: If this switch is used inside the preamble of the source file UDO won't print a specific preamble for the destination format. The example shows how to suppress the preamble for LaTeX. You shall have some knowledge about the destination format if you want to write your own preamble. Example: !no_preamble [tex] F.12.9 !no_quotes ------------------ Type & position: switch, preamble Syntax: !no_quotes [] Description: Says UDO not to replace double quotes and double apostrophes by real quotes and apostrophes. Example: !no_quotes [asc,man] See: Double quotes, Double apostrophes F.12.10 !no_toc_subnodes ------------------------- Type & position: switch, preamble Syntax: !no_toc_subnodes Description: If you use this switch inside the preamble UDO will print only the chapter titles inside the table of contents. !no_toc_subnodes is the same as !use_short_toc. Example: !no_toc_subnodes [win] See: !tableofcontents F.12.11 !no_toc_subsubnodes ---------------------------- Type & position: switch, preamble Syntax: !no_toc_subsubnodes Description: If you use this switch inside the preamble UDO will print only the chapter titles and section titles inside the table of contents. Example: !no_toc_subsubnodes [win,stg,html] See: !tableofcontents F.12.12 !no_toc_subsubsubnodes ------------------------------- Type & position: switch, preamble Syntax: !no_toc_subsubsubnodes Description: If you use this switch inside the preamble UDO will print only the chapter titles, section titles and subsection titles inside the table of contents. Example: !no_toc_subsubsubnodes [win,stg,html] See: !tableofcontents F.12.13 !no_umlaute -------------------- Type & position: switch, preamble Syntax: !no_umlaute [] Description: Switches off the usage of German umlauts. The example show how to switch it off when converting to a manualpage. Umlauts are than replaced by ae, oe, ue, ss, Ae, Oe and Ue. Example: !no_umlaute [man] See: Special characters F.12.14 !no_verbatim_umlaute ----------------------------- Type & position: switch, preamble Syntax: !no_verbatim_umlaute [] Description: Switches off the usage of German umlauts inside a verbatim environment. The example show how to switch it off when converting to LaTeX. Umlauts are than replaced by ae, oe, ue, ss, Ae, Oe and Ue. Example: !no_verbatim_umlaute [tex] See: !begin_verbatim, !end_verbatim, Preformatted text F.12.15 !no_xlinks ------------------- Type & position: switch, preamble Syntax: !no_xlinks [] Description: This command switches off the usage of external links. This is useful if you used external HTML links in a source file that you want to convert to another format that supports external links. The example shows how to suppress the usage of external links when converting to ST-Guide. Example: !no_xlink [stg] See: (!xlink ...) F.12.16 !node -------------- Type & position: command, main part Syntax: !node Description: Starts a new chapter named "". Example: !node Command reference See: !pnode, !subnode, !subsubnode, !subsubsubnode, Structuring F.12.17 !node* --------------- Type & position: command, main part Syntax: !node* Description: This command does the same as !node, but here "" will not appear in a table of contents. Example: !node* Chapter title See: !node, !pnode*, Structuring F.12.18 !nop ------------- Type & position: command, preamble & main part Syntax: !nop Description: This command ("no operation") does nothing and is used for debugging purposes. F.12.19 (!N)...(!n) -------------------- Type & position: placeholder, preamble & main part Syntax: (!N)(!n) Description: "" will be displayed as a footnote or in brakes. Right before (!N) shouldn't be a space, tab or linefeed! Example: the text(!N)the footnote(!n) See: Footnotes F.12.20 (!nl) -------------- Type & position: placeholder, main part Syntax: (!nl) Description: With (!nl) you can force a line break. You must add a space before (!nl) if you use it! Example: breaking (!nl) lines F.13 O... ========== F.14 P... ========== F.14.1 !=pch ------------- Type & position: command, preamble & main part Syntax: !=pch Description: "" will only be printed if you don't convert into Pure C Help. "" will be not converted! See: !pch, !ifdest, raw environment F.14.2 !parwidth ----------------- Type & position: switch, preamble Syntax: !parwidth Description: With this switch you can tell UDO which width it should use for the lines it saves. UDO uses 70 by default. You can change this value by using a between 20 and 200. When converting to Windows Help, Apple QuickView or HTML you can use a value that's greater than 200 if you use the switch !use_output_buffer. Example: !parwidth 98 See: !use_output_buffer F.14.3 !pch ------------ Type & position: command, preamble & main part Syntax: !pch Description: "" is only given out if you convert into Pure C Help. "" will be not converted! See: !=pch, raw environment F.14.4 !pnode -------------- Type & position: command, main part Syntax: !pnode Description: The same as !node but the contents will be displayed as a popup inside ST-Guide and WinHelp. Example: !popup Popup title See: !psubnode, !psubsubnode, !psubsubsubnode F.14.5 !pnode* --------------- Type & position: command, main part Syntax: !pnode* Description: This command does the same as !pnode, but here "" will not appear in a table of contents. Example: !pnode Popup title See: !pnode, !node*, Structuring F.14.6 !program ---------------- Type & position: command, preamble Syntax: !program Description: "" will be displayed on the titlepage below the title. Example: !program UDO See: !maketitle, !programimage, Title page F.14.7 !programimage --------------------- Type & position: command, preamble Syntax: !programimage Description: "" will be displayed instead of the name of the program on the titlepage if the destination format supports images. Example: !programimage udo See: !maketitle, !program, Title page F.14.8 !psubnode ----------------- Type & position: command, main part Syntax: !psubnode Description: The same as !subnode but the contents will be displayed as a popup inside ST-Guide and WinHelp. Example: !psubnode A popup section See: !pnode, !psubsubnode, !psubsubsubnode F.14.9 !psubnode* ------------------ Type & position: command, main part Syntax: !psubnode* Description: This command does the same as !psubnode, but here "" will not appear in a table of contents. Example: !psubnode* A hidden popup section See: !psubnode, !subnode*, Structuring F.14.10 !psubsubnode --------------------- Type & position: command, main part Syntax: !psubsubnode Description: The same as !subsubnode but the contents will be displayed as a popup inside ST-Guide and WinHelp. Example: !psubsubnode A popup subsection See: !pnode, !psubnode, !psubsubsubnode F.14.11 !psubsubnode* ---------------------- Type & position: command, main part Syntax: !psubsubnode* Description: This command does the same as !psubsubnode, but here "" will not appear in a table of contents. Example: !psubsubnode* A hidden popup subsection See: !psubsubnode, !subsubnode*, Structuring F.14.12 !psubsubsubnode ------------------------ Type & position: command, main part Syntax: !psubsubsubnode Description: The same as !subsubsubnode but the contents will be displayed as a popup inside ST-Guide and WinHelp. Example: !psubsubsubnode A popup paragraph See: !pnode, !psubnode, !psubsubnode F.14.13 !psubsubsubnode* ------------------------- Type & position: command, main part Syntax: !psubsubsubnode* Description: This command does the same as !psubsubsubnode, but here "" will not appear in the table of contents. Example: !psubsubsubnode* A hidden popup paragraph See: !pnode, !psubnode, !psubsubnode, !psubsubsubnode F.14.14 (!plink~..) -------------------- Type & position: placeholder, main part Syntax: (!plink [] []) Description: Only useful when converted to LaTeX where it's converted into a page reference. Example: (!plink [word] [label]) See: (!link ...), (!xlink ...), Links F.15 R... ========== F.15.1 !=rtf ------------- Type & position: command, preamble & main part Syntax: !=rtf Description: "" will only be printed if you don't convert into RTF. "" will be not converted! See: !rtf, !ifdest, raw environment F.15.2 !rinclude ----------------- Type & position: command, main part Syntax: !rinclude Description: "" will be included and output unforformated inside a raw environment. Useful for large tables for LaTeX or HTML. Example: !rinclude table.tex See: !include, !vinclude, Split documents, raw environ- ment F.15.3 !rtf ------------ Type & position: command, preamble & main part Syntax: !rtf Description: "" is only given out if you convert into RTF. "" will be not converted! See: !=rtf, raw environment F.15.4 !rtf_charwidth ---------------------- Type & position: switch, preamble & main part Syntax: !rtf_charwidth Description: UDO uses a constant value for calulating the indent of lists and the widths of table cells. This value works even fine with bold monospaced capital letters, but if you use normal text the indents or table cells my be too width. You can adjust this value by using !rtf_charwidth. UDO uses 150 by default. Example: !rtf_charwidth 100 See: Tables, Lists F.15.5 !rtf_monofont --------------------- Type & position: command, preamble Syntax: !rtf_monofont Description: With this command you can set the font that will be used to display preformated text. The default is "Monospace 821". Example: !rtf_monofont Courier New See: !rtf_propfont F.15.6 !rtf_no_tables ---------------------- Type & position: switch, preamble Syntax: !rtf_no_tables Description: If you use this command inside the preamble UDO prints tables without using special RTF commands. It will print the table ASCII like with a monospaced font. See: Tables F.15.7 !rtf_propfont --------------------- Type & position: command, preamble Syntax: !rtf_propfont Description: With this command you can set the font that will be used to display text and headings. The default is "Dutch 801 Roman". Example: !rtf_propfont Times New Roman See: !rtf_monofont F.16 S... ========== F.16.1 !=stg ------------- Type & position: command, preamble & main part Syntax: !=stg Description: "" will only be printed if you don't convert into ST-Guide. "" will be not converted! See: !stg, !ifdest, raw environment F.16.2 !set ------------ Type & position: command, preamble & main part Syntax: !set Description: With this command you can set symbols inside your source file that you can check with !ifset and !if. Symbols may alos be set by the command line option -D. With the !unset command you can delete symbols. You can use !set wherever you want. Example: !set UseColourGraphics See: !unset, !ifset, !ifnset F.16.3 !short -------------- Type & position: switch, main part Syntax: !short Description: If you use this switch together with environments this specific environment will be printed without additional vertical space. The example shows how to print a "compressed" itemize environment. Example: !begin_itemize !short See: !begin_itemize, !begin_enumerate, !begin_description, !use_short_envs F.16.4 !sloppy --------------- Type & position: switch, main part Syntax: !sloppy Description: Switches off warning messages according short lines. You can use this command wherever you want. The warnings can be enabled with !fussy. When converting to LaTeX UDO doesn't convert !sloppy into \sloppy! See: !fussy F.16.5 !smallskip ------------------ Type & position: command, main part Syntax: !smallskip Description: This command will be simplay replaced by "\smallskip" when converted to LaTeX. Otherwise one additional empty line will be generated. See: !medskip, !bigskip F.16.6 !sort_hyphen_file ------------------------- Type & position: switch, preamble Syntax: !sort_hyphen_file [] Description: If this switch is used inside the preamble UDO will read the hyphenation file, delete entries that are used more than once and will save a sorted version of this hyphenation file. The example shows how to do this for ASCII and ST-Guide. Example: !sort_hyphen_file [asc,stg] See: !hyphen F.16.7 !stg ------------ Type & position: command, preamble & main part Syntax: !stg Description: "" is only given out if you convert into ST- Guide. "" will be not converted! Example: !stg @subject "Documentation\Utilities See: !=stg, raw environment F.16.8 !stg_no_database ------------------------ Type & position: switch, preamble Syntax: !stg_no_database Description: Switches off the output of the ST-Guide @database line. F.16.9 !street --------------- Type & position: command, preamble Syntax: !street Description: "" will be displayed below the name of the author to show in which street you live. Example: !street Asmecke 1 See: !maketitle, Title page F.16.10 !subheading -------------------- Type & position: command, main part Syntax: !subheading Description: This command prints out "" as a headline using the section font and fontsize. See: !heading, !subsubheading F.16.11 !subnode ----------------- Type & position: command, main part Syntax: !subnode Description: Starts a new section named "". Example: !subnode Section title See: !node, !subsubnode, !subsubsubnode, Structuring F.16.12 !subnode* ------------------ Type & position: command, main part Syntax: !subnode* Description: This command does the same as !subnode, but here "" will not appear in a table of contents. Example: !subnode* Section title See: !subnode, !psubnode*, Structuring F.16.13 !subsubheading ----------------------- Type & position: command, main part Syntax: !subsubheading Description: This command prints out "" as a headline using the subsubnode font and fontsize. See: !heading, !subheading F.16.14 !subsubnode -------------------- Type & position: command, main part Syntax: !subsubnode Description: Starts a new subsection named "". Example: !subsubnode Subsection title See: !node, !subnode, Structuring F.16.15 !subsubnode* --------------------- Type & position: command, main part Syntax: !subsubnode* Description: This command does the same as !subsubnode, but here "" will not appear in a table of contents. Example: !subsubnode* Subsection title See: !subsubnode, !psubsubnode*, Structuring F.16.16 !subsubsubheading -------------------------- Type & position: command, main part Syntax: !subsubsubheading Description: This command prints out "" as a headline using the subsubsubnode font and fontsize. See: !heading, !subheading, !subsubheading F.16.17 !subsubsubnode ----------------------- Type & position: command, main part Syntax: !subsubsubnode Description: Starts a new paragraph named "". Paragraphs are numbered with #.#.#.# and are displayed inside the table of contents Example: !subsubsubnode Paragraph title See: !psubsubsubnode, !subnode, !subsubnode, Structuring F.16.18 !subsubsubnode* ------------------------ Type & position: command, main part Syntax: !subsubsubnode* Description: This command does the same as !subsubsubnode, but here "" will not appear in the table of contents. Example: !subsubsubnode* Paragraph title See: !psubsubsubnode, !subnode, !subsubnode, Structuring F.16.19 !subsubtoc ------------------- Type & position: command, main part Syntax: !subsubtoc Description: Lists all subsections of a section to enable the reader of a hypertext to switch to the subsections. Example: !subsubtoc [html,pch,stg,win] See: !tableofcontents, !toc, !subtoc, !use_auto_subsubtocs, Tables of contents F.16.20 !subtoc ---------------- Type & position: command, main part Syntax: !subtoc Description: Lists all sections of a chapter to enable the reader of a hypertext to siwtch to the sections. Example: !subtoc [html,pch,stg,win] See: !tableofcontents, !toc, !subsubtoc, !use_auto_subtocs, Tables of contents F.16.21 (!short_today) ----------------------- Type & position: placeholder, preamble & main part Syntax: (!short_today) Description: This placeholder will be replaced by the short form of the current date. Example: (!short_today) becomes 1997/01/04 See: (!today), !language F.17 T... ========== F.17.1 !=tex ------------- Type & position: command, preamble & main part Syntax: !=tex Description: "" will only be printed if you don't convert into LaTeX. "" will be not converted! See: !tex, !ifdest, raw environment F.17.2 !table_caption ---------------------- Type & position: command, main part Syntax: !table_caption Description: Use this command to set the title of the next table. You have to use this command outside the table envi- ronment. For the first table of your source file UDO will print "Table 1: A table" if you use the lower example. Example: !table_caption A table See: Tables, !table_caption* F.17.3 !table_caption* ----------------------- Type & position: command, main part Syntax: !table_caption* Description: The difference between this and the !table_caption command is that UDO won't print "Table :" before the table caption. Example: !table_caption* A table See: Tables, !table_caption F.17.4 !table_counter ---------------------- Type & position: switch, preamble Syntax: !table_counter [] Description: With this switch you can set the table counter. If you use the lower example the caption of the first table will look like this: "Table 5: ...". Example: !table_counter 5 See: Tables F.17.5 !tableofcontents ------------------------ Type & position: command, main part Syntax: !tableofcontents Description: Generates a full table of contents with specific commands of the destination format. I recommend to use this command right after using !begin_document or !maketitle. See: Tables of contents, !use_short_toc F.17.6 !tabwidth ----------------- Type & position: command, preamble & main part Syntax: !tabwidth Description: If lines that are part of a verbatim environment contain TABs (ASCII 9) UDO will replace them by a specific number of blanks. E.g. if you have written a C source code using a tabwidth of 3 and you want to print it with UDO you can use !tabwidth 3. You can reset this value before every verbatim environ- ment. UDO will use a value of 8 by default. Example: !tabwidth 3 See: verbatim environment, !vinclude F.17.7 !tex ------------ Type & position: command, preamble & main part Syntax: !tex Description: "" is only given out if you convert into LaTeX. "" will be not converted! Example: !tex \parindent 0pt See: !=tex, raw environment F.17.8 !tex_2e --------------- Type & position: switch, preamble Syntax: !tex_2e Description: UDO will output special LaTeX2e commands if you use this command e.g. \textbf{...} instead of {\bf ...} F.17.9 !tex_dpi ---------------- Type & position: command, preamble & main part Syntax: !tex_dpi Description: Sets the resolution with which images should be output via LaTeX. Example: !tex_dpi 100 See: !tex_strunk, !tex_lindner, !tex_emtex, !image, Images F.17.10 !tex_emtex ------------------- Type & position: switch, preamble Syntax: !tex_emtex Description: This switch says UDO to generate special emTeX commands to display Microsoft Paintshop Bitmaps (*.msp) when using the !image command. See: !tex_strunk, !tex_lindner, !image, Images F.17.11 !tex_lindner --------------------- Type & position: switch, preamble Syntax: !tex_lindner Description: This switch says UDO to generate special Lindner-TeX commands to display GEM images when using the !image command. See: !tex_strunk, !tex_emtex, !image, Images F.17.12 !tex_strunk -------------------- Type & position: switch, preamble Syntax: !tex_strunk Description: This switch says UDO to generate special Strunk-TeX commands to display GEM images when using the !image command. See: !tex_lindner, !tex_emtex, !image, Images F.17.13 !tex_verb ------------------ Type & position: command, preamble & main part Syntax: !tex_verb Description: " Description: "" will be displayed on the titlepage before the contents of !program. It's also used inside the headlines. Example: !title The guide to See: !maketitle, Title page F.17.15 !toc ------------- Type & position: command, main part Syntax: !toc [] Description: Outputs a table of contents without special page or hypertext commands. The example shows how to output a table of contents (as raw text) for the ST-Guide. Example: !toc [stg] See: !tableofcontents, !subtoc, !subsubtoc, Tables of contents F.17.16 !toc_offset -------------------- Type & position: switch, preamble Syntax: !toc_offset Description: "" is added to the current chapter number when printing a chapter headline or a table of contents. The example shows how to set the number of the first chapter to 10. You can use negative values, too. This switch has no effect to chapters of the appendix. Example: !toc_offset 9 F.17.17 !town -------------- Type & position: command, preamble Syntax: !town Description: "" will be given out inside the author's address block on the titlepage. Example: !town D-59846 Sundern See: !maketitle, Title page F.17.18 (!T)...(!t) -------------------- Type & position: placeholder, preamble & main part Syntax: (!T)(!t) Description: "" will be displayed in typewriter if possible. Example: (!T)monospaced(!t) See: Emphasizing text F.17.19 (!TeX) --------------- Type & position: placeholder, preamble & main part Syntax: (!TeX) Description: This placeholder will be replaced by \TeX{} when converting to LaTeX. Otherwise it will be replace by "TeX". Example: (!TeX) is printed as TeX See: (!LaTeX), (!LaTeXe) F.17.20 (!today) ----------------- Type & position: placeholder, preamble & main part Syntax: (!today) Description: This placeholder will be replaced by the long form of the current date. Example: (!today) becomes January 4, 1997 See: (!short_today), !language F.18 U... ========== F.18.1 !universal_charset -------------------------- Type & position: switch, preamble & main part Syntax: !universal_charset [ on | off ] Description: `!universal_charset [on]' switches on the usage of the universal charset, `!universal_charset [off]' switches it off. UDO won't use the universal charset by default because it takes some time to look for and convert these special characters. Example: !universal_charset [on] See: Universal charset F.18.2 !unset -------------- Type & position: command, preamble & main part Syntax: !unset Description: With this command you can delete a symbol that was set with !set or with the command line option -D. See: !set, !ifset, !ifnset, Symbols F.18.3 !use_about_udo ---------------------- Type & position: switch, preamble Syntax: !use_about_udo [] Description: This command switches on the usage of a page with information about UDO. This page doesn't appear in tables of contents. If you want to tell anybody else about UDO please add this switch to your preamble and insert `UDO5' somewhere in your source file. The example shows how to add this information page in Windows Help, ST-Guide and Pure C Help. Example: !use_about_udo [stg,win,pch] F.18.4 !use_alias_inside_index ------------------------------- Type & position: switch, preamble Syntax: !use_alias_inside_index [] Description: If you use this switch inside the preamble of your source file all aliases will be printed in the index of the given destination formats. Example: !use_alias_inside_index [win,stg] See: Indices, !no_index, !index, !alias F.18.5 !use_ansi_tables ------------------------ Type & position: switch, preamble Syntax: !use_ansi_tables [] Description: If you use this switch inside the preamble tables will be printed with graphic chars from the DOS characterset. This switch has no function when converting into LaTeX, WinHelp or HTML. Example: !use_ansi_tables [stg] See: !begin_table, Tables F.18.6 !use_auto_subsubsubtocs ------------------------------- Type & position: switch, preamble Syntax: !use_auto_subsubsubtocs [] Description: Tells UDO to use the !subsubsubtoc command automatically in every subsection. The example shows how to use them inside the hypertext formats. Example: !use_auto_subsubsubtocs [html,pch,stg,win] See: !subsubsubtoc, !ignore_subsubsubtoc, Tables of contents F.18.7 !use_auto_subsubtocs ---------------------------- Type & position: switch, preamble Syntax: !use_auto_subsubtocs [] Description: Tells UDO to use the !subsubtoc command automatically in every section. The example shows how to use them inside the hypertext formats. Example: !use_auto_subsubtocs [html,pch,stg,win] See: !subsubtoc, !ignore_subsubtoc, Tables of contents F.18.8 !use_auto_subtocs ------------------------- Type & position: switch, preamble Syntax: !use_auto_subtocs [] Description: Tells UDO to use the !subtoc command automatically in every chapter. The example shows how to use them inside the hypertext formats. Example: !use_auto_subtocs [html,pch,stg,win] See: !subtoc, !ignore_subtoc, Tables of contents F.18.9 !use_chapter_images --------------------------- Type & position: switch, preamble Syntax: !use_chapter_images [] Description: This command switches on the usage of chapter images instead of chapter titles. Chapters that use the !chapterimage command will use an image instead. The example demonstrates this for Windows Help, HTML and ST-Guide). Example: !use_chapter_images [html,win,stg] See: !chapterimage F.18.10 !use_formfeed ---------------------- Type & position: switch, preamble Syntax: !use_formfeed [] Description: With this switch you can tell UDO to output a form feed (ASCII 12) when handling the !newpage-command. Example: !use_formfeed [asc] See: !man_lpp, !newpage F.18.11 !use_justification --------------------------- Type & position: switch, preamble Syntax: !use_justification [] Description: If you use this switch inside the preamble UDO will print text with justification if the destination format supports it. RTF and LaTeX will use justification by default, Windows Help and HTML don't support justification. Example: !use_justification [asc] F.18.12 !use_label_inside_index -------------------------------- Type & position: switch, preamble Syntax: !use_label_inside_index [] Description: If you use this switch inside the preamble of your source file all labels will be printed in the index of the given destination formats. Example: !use_label_inside_index [win,stg] See: Indices, !no_index, !index, !label F.18.13 !use_nodes_inside_index -------------------------------- Type & position: switch, preamble Syntax: !use_nodes_inside_index [] Description: If you use this switch inside the preamble of your source file all chapter titles will be printed in the index of the given destination formats. Example: !use_nodes_inside_index [win,stg] See: Indices, !no_index, !index, !node F.18.14 !use_output_buffer --------------------------- Type & position: switch, preamble Syntax: !use_output_buffer [] Description: For all destination formats UDO breaks lines after the amount of characters you set with !parwidth. When converting to Windows Help or HTML it can happen that UDO makes mistakes when inserting links. If you use this switch UDO will print a complete paragraph into the output buffer, it will then insert the links and in the final step it will break the lines. Because this method slows down the conversion of the source file UDO doesn't use the output Example: !use_output_buffer [win,html] See: !parwidth F.18.15 !use_short_envs ------------------------ Type & position: switch, preamble Syntax: !use_short_envs [] Description: If you use this swicth inside the preamble of your source file UDO will print all environments (without the verbatim environment) without additional horizontal space. The example shows how to use "compressed" environments by default for the ASCII format. Example: !use_short_envs [asc] See: !begin_itemize, !begin_enumerate, !begin_description, !begin_xlist F.18.16 !use_short_toc ----------------------- Type & position: switch, preamble Syntax: !use_short_toc [] Description: Tells UDO to output short tables of contents. In the main table of contents only the names of the chapters and in chapters only the names of sections will be printed. Example: !use_short_toc [all] See: !tableofcontents, Tables of contents F.18.17 !use_style_book ------------------------ Type & position: switch, preamble Syntax: !use_style_book [] Description: When converting into LaTeX UDO outputs \chapter instead of \section, \section instead of \subsection and \subsection instead of \subsubsection. When converting to other formats a booklike output will be made, that means that chapters will be printed as "Chapter #". Example: !use_style_book [tex] F.18.18 (!U)...(!u) -------------------- Type & position: placeholder, preamble & main part Syntax: (!U)(!u) Description: "" will be displayed underlined if possible. Example: (!U)underlined(!u) See: Emphasizing text F.19 V... ========== F.19.1 !verbatimsize --------------------- Type & position: switch, preamble & main part Syntax: !verbatimsize [tiny|small|normal|large|huge] Description: With this switch you can set the font size of verbatim environments if the destination format allows it to use differnet font sizes. You can use this switch wherever you want. The smallest font size is activated with `tiny', the largest one with `huge'. The default font size is `normal'. Example: !verbatimsize [small] See: verbatim environment F.19.2 !version ---------------- Type & position: command, preamble Syntax: !version Description: "" will be given out right below the contents of !program on the titlepage. Example: !version Release 6 See: !maketitle, Title page F.19.3 !vinclude ----------------- Type & position: command, main part Syntax: !vinclude Description: "" will be included and displayed like preformated text inside a verbatim environment. If you use this commands inside another environment UDO indents the contents of this file. UDO converts tabs according to !tabwidth. Example: !vinclude hello.c See: !tabwidth, !include, Split documents, verbatim envi- ronment F.19.4 (!V)...(!v) ------------------- Type & position: placeholder, preamble & main part Syntax: (!V)(!v) Description: "" will be displayed preformated if possible. Example: (!V)preformated(!v) See: Emphasizing text, !tex_verb F.20 W... ========== F.20.1 !=win ------------- Type & position: command, preamble & main part Syntax: !=win Description: "" will only be printed if you don't convert into WinHelp. "" will be not converted! See: !win, !ifdest, raw environment F.20.2 !win ------------ Type & position: command, preamble & main part Syntax: !win Description: "" is only given out if you convert into Windows Help. "" will be not converted! See: !=win, raw environment F.20.3 !win_background ----------------------- Type & position: command, preamble Syntax: !win_background [] Description: With this command you can set the background colour of your Windows Help file. You can use one of the following colours: red, green, blue, cyan, magenta, yellow, grey and white. But you should use only white, grey and black because the other colours are quite ugly. Example: !win_backgound grey F.20.4 !win_charwidth ---------------------- Type & position: switch, preamble & main part Syntax: !win_charwidth Description: UDO uses a constant value for calulating the indent of lists and the widths of table cells. This value works even fine with bold monospaced capital letters, but if you use normal text the indents or table cells my be too width. You can adjust this value by using !rtf_charwidth. UDO uses 150 by default. Example: !win_charwidth 100 See: Tables, Lists F.20.5 !win_high_compression ----------------------------- Type & position: switch, preamble Syntax: !win_high_compression Description: If you use this switch inside the preamble the Microsoft Helpcompiler will compress the Windows Help file by about 50%. The compression of the Windows Help file takes some time. A similar result with a faster compression you will get with !win_medium_compression. See: !win_medium_compression F.20.6 !win_inline_bitmaps --------------------------- Type & position: switch, preamble Syntax: !win_inline_bitmaps Description: If you use this switch inside the preamble of your source file UDO will use the RTF tag `\bmcwd' instead of `\bmc' for displaying images. In this case you cannot use images larger than 64 KB. Please read the HCP documentation to get more information about the differences between these two RTF tags. See: !image F.20.7 !win_medium_compression ------------------------------- Type & position: switch, preamble Syntax: !win_medium_compression Description: If you use this switch inside the preamble the Microsoft Helpcompiler will compress the Windows Help file by about 40%. A better result with a slower compression you will get with !win_high_compression. See: !win_high_compression F.20.8 !win_propfont --------------------- Type & position: command, preamble Syntax: !win_propfont Description: With this command you can set the font that will be used to display text inside a Windows Help hypertext. The default is "Times New Roman". Example: !win_propfont Arial F.21 X... ========== F.21.1 (!xlink ...) -------------------- Type & position: placeholder, main part Syntax: (!xlink [] []) Description: Useful for references to external documents like other hypertexts ore WWW-pages. In contrast to (!link ...) will not be converted! The example shows how to make a link to a popular magazine in a HTML file. If is empty the contents of is used. Example: (!xlink [Playboy] [http://www.playboy.com]) See: (!link ...), (!plink ...), !no_xlinks, Links F.22 *... ========== F.22.1 !~ ---------- Type & position: special character(s), preamble & main part Syntax: !~ Description: These characters will be printed as a tilde. Please remember that a single tilde is used for a non- breaking space. Example: !~ becomes to ~ See: ~, Non-breaking spaces F.22.2 !- ---------- Type & position: special character(s), preamble & main part Syntax: !- Description: With these characters you can mark the positions of a word where UDO is allowed to split it up. The example shows how to mark the syllables of "syllabi- fication". Example: syl!-labi!-fi!-cation See: !hyphen F.22.3 !! ---------- Type & position: special character(s), main part Syntax: !! Description: Double exclamation marks are used for splitting the cells of a table row and for multiple indices. Example: !index Level 1 !! Level 2 See: Tables, Indices F.22.4 !.. ----------- Type & position: special character(s), preamble & main part Syntax: !.. Description: An exclamation mark followed by two points will be replaced by typographical three points if the desti- nation format allows it to display them. If not UDO will replace them by three normal points. Example: !.. is converted to ... F.22.5 ~ --------- Type & position: special character(s), preamble & main part Syntax: ~ Description: The tilde is used for a non-breaking space inside the UDO syntax. If a tilde is used between words UDO won't split up them when breaking lines or calculating the justification. Example: 42~DM, Dr.~Helmut Kohl See: !~, Non-breaking spaces F.22.6 "" ---------- Type & position: special character(s), preamble & main part Syntax: "" Description: Two quotes in a row will be replaced by one typo- graphical quote if the destination format supports typographical quotes. If it doesn't UDO will replace two quotes by one quote. Example: "typographical quotes" See: ("") F.22.7 ("") ------------ Type & position: special character(s), preamble & main part Syntax: ("") Description: If you want to print two quotes you have to insert them between brackets. If you don't UDO will replace the two quotes by a typographical quote. See: "" F.22.8 ('') ------------ Type & position: special character(s), preamble & main part Syntax: ('') Description: If you want to print two apostrophes you have to insert them between brackets. If you don't UDO will replace the two apostrophes by a typographical apostrophe. See: '' F.22.9 (--) ------------ Type & position: special character(s), preamble & main part Syntax: (--) Description: If you want to print two minus characters you have to insert them between brackets. If you don't UDO will replace the two minus characters by a short dash. See: --, (---), Dashs F.22.10 (---) -------------- Type & position: special character(s), preamble & main part Syntax: (---) Description: If you want to print three minus characters you have to insert them between brackets. If you don't UDO will replace the three minus characters by a long dash. See: ---, (--), Dachs F.22.11 '' ----------- Type & position: special character(s), preamble & main part Syntax: "" Description: Two apostrophes in a row will be replaced by one ty- pographical apostrophe if the destination format supports typographical apostrophes. If it doesn't UDO will replace two apostrophes by one apostrophe. Example: `typographical apostrophes' See: ('') F.22.12 -- ----------- Type & position: special character(s), preamble & main part Syntax: -- Description: Two minus characters in a row will be replaced by a short dash if the destination format supports them. If the destination format doesn't support them UDO will print one normal minus character instead. Example: A short - er, ah - dash. See: (--), Dashs F.22.13 --- ------------ Type & position: special character(s), preamble & main part Syntax: --- Description: Three minus characters in a row will be replaced by a long dash if the destination format supports them. If the destination format doesn't support them UDO will print one normal minus character instead. Example: A long - er, ah - dash See: (---), Dashs ====================================================================== Appendix UDO6 ====================================================================== This text was made with UDO Release 6 Patchlevel 0 HP-UX Copyright (c) 1995, 1996, 1997 by Dirk Hagedorn Asmecke 1 59846 Sundern Germany MausNet: Dirk Hagedorn@MK2 America Online: DirkHage@aol.com UDO is a program that converts files that are written in the Universal Document Format into ASCII, ST-Guide, LaTeX, Rich Text Format, Pure C Help, Manualpage, HTML, WinHelp ,Texinfo, Linuxdoc-SGML, LyX, Apple QuickView and Turbo-Vision-Help. Further information and the current versions can be found at http://members.aol.com/UDOENG/index.htm